3.6. OGC API Features

OGC API Features (OAPIF) is the first implementation of the new generation of OGC protocols. It is described by the OGC API - Features - Part 1: Core document.

Here is a quick informal summary of the most important differences between the well known WFS protocol and OAPIF:

  • OAPIF is based on a REST API

  • OAPIF must follow the OPENAPI specifications

  • OAPIF supports multiple output formats but it does not dictate any (only GeoJSON and HTML are currently available in QGIS OAPIF) and it uses content negotiation to determine which format is to be served to the client

  • JSON and HTML are first class citizens in OAPIF

  • OAPIF is self-documenting (through the /api endpoint)

  • OAPIF is fully navigable (through links) and browsable

Important

While the OGC API Features implementation in QGIS can make use of the MAP parameter to specify the project file, no extra query parameters are allowed by the OPENAPI specification. For this reason it is strongly recommended that MAP is not exposed in the URL and the project file is specified in the environment by other means (i.e. setting QGIS_PROJECT_FILE in the environment through a web server rewrite rule).

Note

Le point de terminaison API fournit une documentation complète de tous les paramètres et formats de sortie pris en charge de votre service. Les paragraphes suivants ne décrivent que les plus importants.

3.6.1. Représentation des ressources

The implementation of OGC API Features in QGIS Server currently supports the following resource representation (output) formats:

  • HTML

  • JSON

Le format réellement servi dépendra de la négociation de contenu, mais un format spécifique peut être explicitement demandé en ajoutant un spécificateur de format aux points de terminaison.

Les extensions de spécificateur de format prises en charge sont:

  • .json

  • .html

Des alias de spécificateur de format supplémentaires peuvent être définis par des points de terminaison spécifiques:

  • .openapi: alias pour .json pris en charge par le point de terminaison API

  • .geojson: alias pour .json pris en charge par les points de terminaison Features et Feature

3.6.2. Points de terminaison

L’API fournit une liste de points de terminaison que les clients peuvent récupérer. Le système est conçu de telle manière que chaque réponse fournit un ensemble de liens pour naviguer à travers toutes les ressources fournies.

Les points de terminaison fournis par l’implémentation de QGIS sont:

Nom

Chemin

Description

Page de destination

/

Informations générales sur le service et fournit des liens vers tous les points de terminaison disponibles

Conformité

/conformance

Informations sur la conformité du service aux normes

API

/api

Description complète des noeuds finaux fournis par le service et de la structure des documents retournés

Les collections

/collections

Liste de toutes les collections (c’est-à-dire « couches vectorielles ») fournies par le service

Collection

/collections/{collectionId}

Informations sur une collection (nom, métadonnées, étendue, etc.)

Fonctionnalités

/collections/{collectionId}/items

Liste des entités fournies par la collection

Entité

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

Informations sur une seule entité

Page de destination

Le critère d’évaluation principal est la page destination. À partir de cette page, il est possible de naviguer vers tous les points de terminaison de service disponibles. La page de destination doit fournir des liens vers

  • la définition de l’API (chemin d’accès /api relations de liaison service-desc et service-doc),

  • la déclaration de conformité (chemin /conformance, relation de liaison conformance), et

  • les Collections (chemin /collections, relation de lien data).

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

Fig. 3.23 Server OAPIF landing page

Définition de l’API

La Définition API est une description conforme à OPENAPI de l’API fournie par le service. Dans sa représentation HTML, il s’agit d’une page consultable où tous les points de terminaison et leurs formats de réponse sont répertoriés et documentés avec précision. Le chemin de ce point de terminaison est /api.

La définition de l’API fournit une documentation complète et faisant autorité du service, y compris tous les paramètres pris en charge et les formats renvoyés.

Note

Ce point de terminaison est analogue aux GetCapabilities de WFS

Liste des collections

Le point de terminaison des collections fournit une liste de toutes les collections disponibles dans le service. Étant donné que le service « serves  » un seul projet QGIS, les collections sont les couches vectorielles du projet en cours (si elles ont été publiées en tant que WFS dans les propriétés du projet). Le chemin de ce point de terminaison est /collections/.

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

Fig. 3.24 Server OAPIF collections list page

Détail de la collection

Bien que le point de terminaison des collections ne fournisse pas d’informations détaillées sur chaque collection disponible, ces informations sont disponibles dans les points de terminaison /collections/{collectionId}. Les informations typiques incluent l’étendue, une description, les SCR et autres métadonnées.

La représentation HTML fournit également une carte consultable avec les entités disponibles.

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

Fig. 3.25 Server OAPIF collection detail page

Liste des entités

Ce point de terminaison fournit une liste de toutes les entités d’une collection connaissant l’ID de la collection. Le chemin de ce noeud final est /collections/{collectionId}/items .

La représentation HTML fournit également une carte consultable avec les entités disponibles.

Note

Ce point de terminaison est analogue à GetFeature dans WFS 1 et WFS 2.

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

Fig. 3.26 Server OAPIF features list page

Détail des entités

Ce point de terminaison fournit toutes les informations disponibles sur une seule entité, y compris les attributs de l’entité et sa géométrie. Le chemin de ce point de terminaison est /collections/{collectionId}/items/{itemId}.

La représentation HTML fournit également une carte consultable avec la géométrie de l’entité.

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

Fig. 3.27 Server OAPIF feature detail page

3.6.3. Pagination

La pagination d’une longue liste d” entités est implémentée dans l’API OGC via des liens suivant et précédent, QGIS serveur construit ces liens en ajoutant limite et décalage comme paramètres de chaîne de requête.

Exemple d’URL :

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

Note

La valeur maximale acceptable pour limit peut être configurée avec le paramètre de configuration du serveur QGIS_SERVER_API_WFS3_MAX_LIMIT (voir Variables d’environnement).

3.6.4. Filtrage des entités

Les entités disponibles dans une collection peuvent être filtrées / recherchées en spécifiant un ou plusieurs filtres.

Filtre date et heure

Les collections avec des attributs date et / ou datetime peuvent être filtrées en spécifiant un argument datetime dans la chaîne de requête. Par défaut, le premier champ date / datetime est utilisé pour le filtrage. Ce comportement peut être configuré en définissant une dimension « Date » ou « Heure » dans QGIS Server -> Dimension de la boîte de dialogue des propriétés de la couche.

La syntaxe de filtrage de la date et de l’heure est entièrement décrite dans Définition de l’API et prend également en charge les plages (les valeurs de début et de fin sont incluses) en plus des valeurs uniques.

Exemples d’URL:

Renvoie uniquement les entités dont la dimension de date correspond à 2019-01-01

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

Renvoie uniquement les entités dont la dimension datetime correspond à 2019-01-01T01: 01: 01

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

Renvoie uniquement les entités dont la dimension datetime se situe dans la plage 2019-01-01T01: 01: 01 - 2019-01-01T12: 00: 00

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

Filtre de boîte englobante

Un filtre spatial de boîte englobante peut être spécifié avec le paramètre bbox :

L’ordre des éléments séparés par des virgules est le suivant:

  • Coin inférieur gauche, longitude WGS 84

  • Coin inférieur gauche, latitude WGS 84

  • Coin supérieur droit, longitude WGS 84

  • Coin supérieur droit, latitude WGS 84

Note

Les spécifications OGC autorisent également un spécificateur bbox à 6 éléments où les troisième et sixième éléments sont les composants Z, ce qui n’est pas encore pris en charge par le serveur QGIS.

Exemple d’URL :

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

Si le CRS de la boîte englobante n’est pas WGS 84, un CRS différent peut être spécifié en utilisant le paramètre optionnel bbox-crs. L’identificateur de format du CRS doit être au format OGC URI :

Exemple d’URL :

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

Filtres d’attributs

Les filtres d’attribut peuvent être combinés avec le filtre de boîte englobante et ils se présentent sous la forme générale: 1=2. Plusieurs filtres peuvent être combinés à l’aide de l’opérateur AND.

Exemple d’URL :

filtre toutes les entités où l’attribut ``name` est égal à « ma valeur »

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

Les correspondances partielles sont également prises en charge en utilisant un opérateur * (« etoile »):

Exemple d’URL :

filtre toutes les entités où l’attribut name se termine par « value »

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

3.6.5. Tri des éléments

Il est possible d’ordonner le résultat par valeur de champ en utilisant le paramètre d’interrogation « sortby ».

Par défaut, les résultats sont triés par ordre croissant. Pour trier les résultats par ordre décroissant, un drapeau booléen (sortdesc) peut être activé :

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

3.6.6. Sélection d’attribut

Les attributs d’entité renvoyés par un appel Liste des entités peuvent être limités en ajoutant une liste de noms d’attributs séparés par des virgules dans l’argument de chaîne de requête facultatif propriétés.

Exemple d’URL :

renvoie uniquement l’attribut name

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

3.6.7. Personnaliser les pages HTML

The HTML representation uses a set of HTML templates to generate the response. The template is parsed by a template engine called inja. The templates can be customized by overriding them (see: Remplacements de modèle). The template has access to the same data that are available to the JSON representation and a few additional functions are available to the template:

Fonctions de modèle personnalisées

  • path_append(path) : ajoute un chemin de répertoire à l’url actuelle

  • path_chomp(n) : supprime le nombre spécifié « n » de composants de répertoire du chemin d’URL actuel

  • json_dump(): affiche les données JSON transmises au modèle

  • static( path ): returns the full URL to the specified static path. For example: « static( « /style/black.css » ) » with a root path « http://localhost/qgisserver/oapif » will return « http://localhost/qgisserver/oapif/static/style/black.css ».

  • links_filter(links, key, value): retourne les liens filtrés d’une liste de liens

  • content_type_name(content_type): renvoie un nom court à partir d’un type de contenu, par exemple « text / html » renverra « HTML »

  • nl2br( text ): Returns the input text with all newlines replaced by « <br> » tags

Remplacements de modèle

Les modèles et les actifs statiques sont stockés dans des sous-répertoires du répertoire de ressources de l’API par défaut du serveur QGIS ( /usr/share/qgis/resources/server/api/ sur un système Linux), le répertoire de base peut être personnalisé en modifiant le variable d’environnement QGIS_SERVER_API_RESOURCES_DIRECTORY.

Une installation Linux typique aura l’arborescence de répertoires suivante:

/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

Pour remplacer les modèles, vous pouvez copier l’arborescence entière vers un autre emplacement et pointer vers le nouvel emplacement. QGIS_SERVER_API_RESOURCES_DIRECTORY