3.6. Funcionalidad API OGC

OGC API Features (OAPIF) es la primera implementación de la nueva generación de los protocolos OGC. Se describen en el documento OGC API - Features - Part 1: Core.

En instalaciones típicas, se puede acceder a la API a través de http://localhost/qgisserver/wfs3.

He aquí un rápido resumen informal de las diferencias más importantes entre el conocido protocolo WFS y la OAPIF:

  • OAPIF se basa en una API REST

  • La OAPIF debe seguir las especificaciones de OPENAPI.

  • OAPIF admite múltiples formatos de salida pero no dicta ninguno (actualmente sólo están disponibles GeoJSON y HTML en QGIS OAPIF) y utiliza la negociación de contenido para determinar qué formato se debe servir al cliente

  • JSON y HTML son ciudadanos de primera clase en OAPIF

  • OAPIF se autodocumenta (a través del punto final /api)

  • La OAPIF es totalmente navegable (a través de enlaces) y navegable

Importante

Mientras que la implementación de las funcionalidades de la API OGC en QGIS puede hacer uso del parámetro MAP para especificar el archivo del proyecto, la especificación de OPENAPI no permite parámetros de consulta adicionales. Por esta razón, se recomienda encarecidamente que no se exponga MAP en la URL y que el archivo del proyecto se especifique en el entorno por otros medios (es decir, estableciendo QGIS_PROJECT_FILE en el entorno a través de una regla de reescritura del servidor web).

Nota

La API punto final proporciona documentación completa de todos los parámetros y formatos de salida admitidos de su servicio. Los siguientes párrafos solo describirán los más importantes.

3.6.1. Representación de recurso

La implementación de las funcionalidades de la API OGC en QGIS Server admite actualmente los siguientes formatos de representación de recursos (salida):

  • HTML

  • JSON

El formato que se sirve realmente dependerá de la negociación de contenido, pero se puede solicitar explícitamente un formato específico agregando un especificador de formato a los puntos finales.

Las extensiones de especificador de formato admitidas son:

  • .json

  • .html

Los alias de especificador de formato adicionales se pueden definir por puntos finales específicos:

  • .openapi: alias para .json soportado por la API endpoint

  • .geojson: alias para .json soportado por los endpoints Features y Feature

3.6.2. Puntos finales

La API proporciona una lista de puntos finales que los clientes pueden recuperar. El sistema está diseñado de tal manera que cada respuesta proporciona un conjunto de enlaces para navegar a través de todos los recursos proporcionados.

Los puntos finales proporcionados por la implementación de QGIS son:

Nombre

Ruta

Descripción

Página de Aterrizaje

/

Información general sobre el servicio y proporciona enlaces a todos los puntos finales disponibles.

Conformidad

/conformance

Información sobre la conformidad del servicio con los estándares.

API

/api

Descripción completa de los puntos finales proporcionados por el servicio y la estructura de los documentos devueltos

Colecciones

/collections

Lista de todas las colecciones (es decir, “capas vectoriales”) proporcionadas por el servicio

Colección

/collections/{collectionId}

Información sobre una colección (nombre, metadatos, extensión, etc.)

Prestaciones

/collections/{collectionId}/items

Lista de los objetos espaciales provistos por la colección

Objeto espacial

/collections/{collectionId}/items/{featureId}

Información acerca de un objeto espacial solo

De forma similar a WFS-T (Web Feature Service transaccional), es posible añadir, actualizar y eliminar características (CRUD). Las solicitudes correspondientes se describen en «/api».

Página de Aterrizaje

El punto final principal es la Página de destino. Desde esa página es posible navegar a todos los puntos finales de servicio disponibles. La página de destino debe proporcionar enlaces a

  • la definición de API (ruta /api relaciones de enlace service-desc y service-doc),

  • la declaración de conformidad (ruta /conformidad, relación de enlace conformidad), y

  • las Colecciones (ruta /colecciones, relación de enlace datos).

../../../_images/server_wfs3_landing_page.png

Figura 3.23 Página de inicio del servidor OAPIF

Definición API

La Definición de API es una descripción compatible con OPENAPI de la API proporcionada por el servicio. En su representación HTML, es una página navegable donde todos los puntos finales y sus formatos de respuesta se enumeran y documentan con precisión. La ruta de este punto final es /api.

La definición de API proporciona una documentación completa y autorizada del servicio, incluidos todos los parámetros admitidos y los formatos devueltos.

Nota

Este punto final es análogo a GetCapabilities de WFS’s

Lista de colecciones

El punto final de colecciones proporciona una lista de todas las colecciones disponibles en el servicio. Dado que el servicio «sirve» a un solo proyecto QGIS, las colecciones son las capas vectoriales del proyecto actual (si se publicaron como WFS en las propiedades del proyecto). La ruta de este punto final es /collections/.

../../../_images/server_wfs3_collections.png

Figura 3.24 Página de la lista de colecciones del servidor OAPIF

Detalle de colección

Si bien el punto final de las colecciones no proporciona información detallada sobre cada colección disponible, esa información está disponible en los puntos finales /collections/{collectionId}. La información típica incluye la extensión, una descripción, SRC y otros metadatos.

La representación HTML también proporciona un mapa navegable con las funciones disponibles.

../../../_images/server_wfs3_collection.png

Figura 3.25 Página de detalles de la colección del servidor OAPIF

Lista de objetos espaciales

Este punto final proporciona una lista de todas las funciones de una colección que conocen el ID de la colección. La ruta de este punto final es /collections/{collectionId}/items.

La representación HTML también proporciona un mapa navegable con las funciones disponibles.

Nota

Este punto final es análogo a GetFeature en WFS 1 y WFS 2.

../../../_images/server_wfs3_features.png

Figura 3.26 Página de la lista de funcionalidades del servidor OAPIF

Detalle de objeto espacial

Este punto final proporciona toda la información disponible sobre una única entidad, incluidos los atributos de la entidad y su geometría. La ruta de este punto final es /collections/{collectionId}/items/{itemId}.

La representación HTML también proporciona un mapa navegable con la geometría de la entidad.

../../../_images/server_wfs3_feature.png

Figura 3.27 Página de detalles de la funcionalidad OAPIF

3.6.3. Paginación

La paginación de una larga lista de características se implementa en la API de OGC a través de enlaces siguiente y anterior, el servidor QGIS construye estos enlaces agregando límite y compensación como parámetros de cadena de consulta.

URL ejemplo:

http://localhost/qgisserver/wfs3/collection_one/items.json?offset=10&limit=10

Nota

El valor máximo aceptable para límite se puede configurar con el ajuste de configuración del servidor QGIS_SERVER_API_WFS3_MAX_LIMIT (ver: Variables de entorno).

3.6.4. Filtrado de objetos espaciales

Las funciones disponibles en una colección se pueden filtrar/buscar especificando uno o más filtros.

Filtro de fecha y hora

Las colecciones con atributos de fecha y / o fecha y hora se pueden filtrar especificando un argumento fecha y hora en la cadena de consulta. De forma predeterminada, el primer campo de fecha / fecha y hora se utiliza para el filtrado. Este comportamiento se puede configurar estableciendo una dimensión de «Fecha» u «Hora» en Servidor QGIS -> Dimensión del cuadro de diálogo de propiedades de la capa.

La sintaxis de filtrado de fecha y hora se describe completamente en Definición API y también admite rangos (se incluyen los valores de inicio y finalización) además de valores únicos.

URL ejemplos:

Devuelve solo las funciones con coincidencia de dimensión de fecha 2019-01-01

http://localhost/qgisserver/wfs3/collection_one/items.json?datetime=2019-01-01

Devuelve solo las funciones con coincidencia de dimensión de fecha y hora 2019-01-01T01:01:01

http://localhost/qgisserver/wfs3/collection_one/items.json?datetime=2019-01-01T01:01:01

Devuelve solo las entidades con dimensión de fecha y hora en el rango 2019-01-01T01:01:01 - 2019-01-01T12:00:00

http://localhost/qgisserver/wfs3/collection_one/items.json?datetime=2019-01-01T01:01:01/2019-01-01T12:00:00

Filtro de recuadro delimitador

Se puede especificar un filtro espacial de cuadro delimitador con el parámetro bbox:

El orden de los elementos separados por comas es:

  • Esquina inferior izquierda, longitud WGS 84

  • Esquina inferior izquierda, latitud WGS 84

  • Esquina superior derecha, longitud WGS 84

  • Esquina superior derecha, latitud WGS 84

Nota

Las especificaciones OGC también permiten un especificador bbox de 6 elementos donde el tercer y sexto elemento son los componentes Z, esto aún no es compatible con el servidor QGIS.

URL ejemplo:

http://localhost/qgisserver/wfs3/collection_one/items.json?bbox=-180,-90,180,90

Si el SRC del cuadro delimitador no es WGS 84, se puede especificar un SRC diferente utilizando el parámetro opcional bbox-crs. El identificador de formato SRC debe estar en el formato ʻOGC URI <https://www.opengis.net/def/crs/>`_:

URL ejemplo:

http://localhost/qgisserver/wfs3/collection_one/items.json?bbox=913191,5606014,913234,5606029&bbox-crs=http://www.opengis.net/def/crs/EPSG/9.6.2/3857

Filtros de Atributos

Los filtros de atributos se pueden combinar con el filtro de cuadro delimitador y están en la forma general: <attribute name>=<attribute value>. Se pueden combinar varios filtros usando el operador «Y».

URL ejemplo:

filtra todas las entidades donde nombre es igual a «mi valor»

http://localhost/qgisserver/wfs3/collection_one/items.json?attribute_one=my%20value

Coincidencias parciales también son soportads usando el operador * («estrella»)

URL ejemplo:

filtra todas las entidades donde el atributo nombre finaliza con «valor»

http://localhost/qgisserver/wfs3/collection_one/items.json?attribute_one=*value

3.6.5. Ordenar Entidad

Es posible ordenar el conjunto de resultados por valor de campo utilizando el parámetro de consulta sortby.

Los resultados se ordenan en orden ascendente de forma predeterminada. Para ordenar los resultados en orden descendente, una bandera booleana (sortdesc) puede establecerse:

http://localhost/qgisserver/wfs3/collection_one/items.json?sortby=name&sortdesc=1

3.6.6. Selección de atributos

Los atributos de características devueltos por una llamada :ref:ʻogc_api_features_features_list` se pueden limitar agregando una lista de nombres de atributos separados por comas en el argumento opcional de cadena de consulta propiedades.

URL ejemplo:

devuelve solo el atributo nombre

http://localhost/qgisserver/wfs3/collection_one/items.json?properties=name

3.6.7. Personaliza las páginas HTML

La representación HTML utiliza un conjunto de plantillas HTML para generar la respuesta. La plantilla es analizada por un motor de plantillas llamado inja. Las plantillas se pueden personalizar anulándolas (ver: Sobreescritura de Plantilla). La plantilla tiene acceso a los mismos datos que están disponibles para la representación JSON y algunas funciones adicionales están disponibles para la plantilla:

Funciones personalizadas de plantilla

  • path_append( path ): adjunta una ruta de directorio a la actual url

  • path_chomp( n ): borra el número especificado «n» de componentes del directorio de la ruta url actual

  • json_dump( ): imprime los datos JSON pasados a la plantilla

  • static( path ): devuelve la URL completa a la ruta estática especificada. Por ejemplo: «static( «/style/black.css» )» con una ruta raiz «http://localhost/qgisserver/wfs3» devolverá «http://localhost/qgisserver/wfs3/static/style/black.css».

  • links_filter( links, key, value ): Devuelve enlaces filtrados de una lista de enlaces

  • content_type_name( content_type ): Devuelve un nombre corto de un tipo de contenido, por ejemplo «text/html» devolverá «HTML»

  • nl2br( text ): Devuelve el texto de entrada con todas los saltos de línea reemplazados por etiquetas «<br>»

  • starts_with( string, prefix ): devuelve true si una cadena comienza con el prefijo de cadena proporcionado, false en caso contrario

Sobreescritura de Plantilla

Las plantillas y los activos estáticos se almacenan en subdirectorios del directorio de recursos de API predeterminado del servidor QGIS (/usr/share/qgis/resources/server/api/ en un sistema Linux), el directorio base se puede personalizar cambiando la variable de entorno QGIS_SERVER_API_RESOURCES_DIRECTORY.

Una instalación típica de Linux tendrá el siguiente árbol de directorios:

/usr/share/qgis/resources/server/api/
└── ogc
    ├── schema.json
    ├── static
    │   ├── jsonFormatter.min.css
    │   ├── jsonFormatter.min.js
    │   └── style.css
    └── templates
        └── wfs3
            ├── describeCollection.html
            ├── describeCollections.html
            ├── footer.html
            ├── getApiDescription.html
            ├── getFeature.html
            ├── getFeatures.html
            ├── getLandingPage.html
            ├── getRequirementClasses.html
            ├── header.html
            ├── leaflet_map.html
            └── links.html

Para anular las plantillas, puede copiar todo el árbol a otra ubicación y señalar QGIS_SERVER_API_RESOURCES_DIRECTORY a la nueva ubicación.