3.6. OGC API Features

OGC API Features (OAPIF) is de eerste implementatie van de nieuwe generatie protocollen van OGC. Het wordt beschreven in het document OGC API - Features - Part 1: Core.

De API kan op normale installaties worden bereikt via http://localhost/qgisserver/wfs3

Hier is een snel informeel overzicht van de meest belangrijke verschillen tussen het welbekende protocol WFS en OAPIF:

  • OAPIF is gebaseerd op een REST API

  • OAPIF moet de specificaties volgen van OPENAPI

  • OAPIF ondersteunt meerdere indelingen voor uitvoer, maar legt er geen verplicht op (alleen GeoJSON en HTML zijn momenteel beschikbaar in QGIS OAPIF) en het gebruikt content negotiation om te bepalen welke indeling aan de cliënt moet worden geserveerd

  • JSON en HTML zijn eerste klas burgers in OAPIF

  • OAPIF is zelf-gedocumenteerd (via het eindpunt /api)

  • OAPIF is volledig te navigeren (via links) en door te bladeren

Belangrijk

Hoewel de implementatie van OGC API Features in QGIS gebruik kan maken van de parameter MAP om het projectbestand te specificeren, zijn geen extra parameters voor query toegestaan door de specificatie van OPENAPI. Om deze reden wordt sterk aanbevolen dat MAP niet wordt weergegeven in de URL en dat het projectbestand in de omgeving op een andere wijze wordt gespecificeerd (d.i. instellen van QGIS_PROJECT_FILE in de omgeving met een regel rewrite voor een webserver).

Notitie

Het eindpunt API verschaft uitgebreide documentatie voor alle ondersteunde parameters en indelingen voor de uitvoer van uw service. De volgende alinea’s zullen alleen de meest belangrijke beschrijven.

3.6.1. Weergavebronnen

De implementatie van OGC API Features in QGIS Server ondersteunt momenteel de volgende weergavebronnen (uitvoer) indelingen:

  • HTML

  • JSON

De indeling die feitelijk wordt geserveerd is afhankelijk van de onderhandeling van de inhoud, maar een specifieke indeling mag expliciet worden verzocht door een specificatie voor de indeling toe te voegen aan de eindpunten.

Ondersteunde extensies voor specificatie van de indeling zijn:

  • .json

  • .html

Aanvullende aliassen voor specificaties van indelingen mogen worden gedefinieerd voor specifieke eindpunten:

  • .openapi: alias voor .json ondersteund door het eindpunt API

  • .geojson: alias voor .json ondersteund door de eindpunten Features en Feature

3.6.2. Eindpunten

De API verschaft een lijst met eindpunten die de cliënten kunnen ophalen. Het systeem is op een dusdanige manier ontworpen dat elk antwoord een set links verschaft om te navigeren door alle verschafte bronnen.

Punten voor eindpunten, verschaft door de QGIS implementatie zijn:

Naam

Pad

Omschrijving

Startpagina

/

Algemene informatie over de service en verschaft links naar alle beschikbare eindpunten

Conformance

/conformance

Informatie over de conformiteit van de service aan de standaarden

API

/api

Volledige beschrijving van de eindpunten, verschaft door de service en de teruggegeven documentstructuur

Collecties

/collections

Lijst van alle collecties (d.i. ‘vectorlagen’) verschaft door de service

Collectie

/collections/{collectionId}

Informatie over een collectie (naam, metadata, bereik etc.)

Functionaliteit

/collections/{collectionId}/items

Lijst met objecten, verschaft door de collectie

Object

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

Informatie over één enkel object

Soortgelijk aan WFS-T (transactionele Web Feature Service), is het mogelijk om objecten toe te voegen, bij te werken en te verwijderen (CRUD). De respectievelijke verzoeken worden beschreven in “/api”.

Startpagina

Het belangrijkste eindpunt is de Startpagina. Vanaf die pagina is het mogelijk om naar alle beschikbare eindpunten van de service te navigeren. De Startpagina moet links verschaffen naar

  • de definitie van de API (pad /api linkrelaties service-desc en service-doc),

  • de declaratie voor Conformance (pad /conformance, linkrelatie conformance), en

  • de Collecties (pad /collections, linkrelatie data).

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

Fig. 3.23 Server OAPIF startpagina

API Definitie

De API Definitie is een OPENAPI-compliant beschrijving van de API die wordt verschaft door de service. In zijn weergave HTML is het een door te bladeren pagina waar alle eindpunten en hun indelingen voor antwoorden nauwgezet zijn vermeld en gedocumenteerd. Het pad van dit eindpunt is /api.

De API definitie verschaft een uitgebreide en betrouwbare documentatie van de service, inclusief alle ondersteunde parameters en teruggegeven indelingen.

Notitie

Dit eindpunt is analoog aan WFS’s GetCapabilities

Lijst Collecties

Het eindpunt Collecties verschaft een lijst met alle beschikbare collecties in de service. Omdat de service één enkel project van QGIS “dient” zijn de collecties de vectorlagen uit het huidige project (indien ze werden gepubliceerd als WFS in de projecteigenschappen). Het pad van dit eindpunt is /collections/.

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

Fig. 3.24 Server OAPIF pagina met lijst van collecties

Detail collectie

Hoewel het eindpunt Collecties geen gedetailleerde informatie verschaft over elke beschikbare collectie, is die informatie beschikbaar in de eindpunten /collections/{collectionId}. Typische informatie omvat het bereik, een beschrijving, CRSen en andere metadata.

De weergave HTML verschaft ook een door te bladeren kaart met de beschikbare objecten.

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

Fig. 3.25 Server OAPIF pagina met detail collectie

Lijst met objecten

Dit eindpunt verschaft een lijst van alle objecten in een collectie, waarvan de ID voor de collectie bekend is. Het pad van dit eindpunt is /collections/{collectionId}/items.

De weergave HTML verschaft ook een door te bladeren kaart met de beschikbare objecten.

Notitie

Dit eindpunt is analoog aan GetFeature in WFS 1 en WFS 2.

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

Fig. 3.26 Server OAPIF pagina met lijst met objecten

Detail object

Dit eindpunt verschaft alle beschikbare informatie over één enkel object, inclusief de attributen van het object en zijn geometrie. Het pad van dit eindpunt is /collections/{collectionId}/items/{itemId}.

De weergave HTML verschaft ook een door te bladeren kaart met de geometrie van het object.

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

Fig. 3.27 Server OAPIF pagina detail object

3.6.3. Paginering

Paginering van een lange lijst met objecten is geïmplementeerd in de OGC API door middel van links next en prev, QGIS server construeert deze links door het toevoegen van limit en offset als parameters voor de tekenreeks van de query.

Voorbeeld URL:

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

Notitie

De maximale te accepteren waarde voor limit kan worden geconfigureerd met de instelling voor de configuratie van de server QGIS_SERVER_API_WFS3_MAX_LIMIT (zie: Omgevingsvariabelen).

3.6.4. Objecten filteren

De beschikbare objecten in een collectie kunnen worden gefilterd/doorzocht door één of meer filters te specificeren.

Filter Datum en tijd

Collecties met attributen date en/of datetime kunnen worden gefilterd door een argument datetime te specificeren in de tekenreeks voor de query. Standaard wordt het eerste veld date/datetime gebruikt voor filteren. Dit gedrag kan worden geconfigureerd door het instellen van een dimensie “Date” of “Time” in het gedeelte QGIS Server ► Dimension van het dialoogvenster Laageigenschappen.

De syntaxis voor filteren van datum en tijd is volledig beschreven in de API Definitie en ondersteunt ook bereiken (begin- en eindwaarden inbegrepen) in aanvulling op enkele waarden.

Voorbeelden URL:

Geeft alleen de objecten terug met de dimensie date die overeenkomt met 2019-01-01

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

Geeft alleen de objecten terug met de dimensie datetime die overeenkomt met 2019-01-01T01:01:01

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

Geeft alleen de objecten terug met de dimensie datetime in het bereik 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

Filter Begrenzingsvak

Een ruimtelijk filter voor een begrenzingsvak kan worden gespecificeerd met de parameter bbox:

De volgorde van de door komma’s gescheiden elementen is:

  • Linkerbenedenhoek, WGS 84 longitude

  • Linkerbenedenhoek, WGS 84 latitude

  • Rechterbovenhoek, WGS 84 longitude

  • Rechterbovenhoek, WGS 84 latitude

Notitie

De specificaties van OGC staan ook een specificatie voor een 6-items begrenzingsvak toe, waarbij de derde en zesde items de componenten Z zijn, dit wordt nog niet ondersteund door QGIS server.

Voorbeeld URL:

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

Als het CRS van het begrenzingsvak niet WGS 84 is, kan een ander CRS worden gespecificeerd met de optionele parameter bbox-crs. De identificatie voor de indeling van het CRS moet zijn in de indeling OGC URI:

Voorbeeld URL:

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

Filters voor attributen

Filters voor attributen kunnen worden gecombineerd met het filter voor het begrenzingsvak en zij mogen in de algemene vorm: <attribute name>=<attribute value> zijn. Meerdere filters mogen worden gecombineerd met de operator AND.

Voorbeeld URL:

filtert alle objecten waarvan het attribuut name gelijk is aan “my value”

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

Gedeeltelijke overeenkomsten worden ook ondersteund door een operator * (“ster”):

Voorbeeld URL:

filtert alle objecten waarvan het attribuut name eindigt op “value”

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

3.6.5. Sorteren van objecten

Het is mogelijk de volgorde van de set met resultaten te sorteren op veldwaarde met de parameter voor de query sortby.

De resultaten worden standaard in oplopende volgorde gesorteerd. Een Booleaanse vlag (sortdesc) kan worden ingesteld om de resultaten in aflopende volgorde te sorteren:

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

3.6.6. Selecteren van attributen

De attributen van een object, die worden teruggegeven door een aanroep Lijst met objecten, kunnen worden beperkt door een kommagescheiden lijst met namen van attributen toe te voegen in het optionele argument properties van de tekenreeks voor de query.

Voorbeeld URL:

geeft alleen het attribuut name terug

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

3.6.7. De HTML-pagina’s aanpassen

De weergave HTML gebruikt een set sjablonen voor HTML om het antwoord te maken. De sjabloon wordt geparset door een sjabloonprogramma, genaamd inja. De sjablonen kunnen worden aangepast door ze te overschrijven (zie: Overschrijven van sjabloon). Het sjabloon heeft toegang tot dezelfde gegevens, als die welke beschikbaar zijn voor de weergave JSON, en een aantal aanvullende functies zijn voor het sjabloon beschikbaar:

Aangepaste functies voor sjabloon

  • path_append( path ): voegt een pad naar een map toe aan de huidige URL

  • path_chomp( n ): verwijdert het gespecificeerde aantal “n” mapcomponenten uit het huidige pad voor de URL

  • json_dump( ): drukt de gegevens voor JSON af die zijn doorgegeven aan de sjabloon

  • static( path ): geeft de volledige URL terug naar het gespecificeerde statische pad. Bijvoorbeeld: “static( “/style/black.css” )” met een bronpad “http://localhost/qgisserver/wfs3” zal teruggeven “http://localhost/qgisserver/wfs3/static/style/black.css”.

  • links_filter( links, key, value ): Geeft gefilterde links terug uit een lijst met links

  • content_type_name( content_type ): Geeft een verkorte naam terug uit een type inhoud, bijvoorbeeld “text/html” zal “HTML” teruggeven

  • nl2br( text ): Geeft de tekst voor de invoer terug waarin alle newlines zijn vervangen door tags “<br>”

  • starts_with( string, prefix ): geeft TRUE terug als een tekenreeks begint met het opgegeven voorvoegsel voor de tekenreeks, anders FALSE

Overschrijven van sjabloon

Sjablonen en statische gegevens worden opgeslagen in submappen van de standaardmap voor de API-bron van de QGIS server (/usr/share/qgis/resources/server/api/ op een systeem van Linux), de basismap kan worden aangepast door de omgevingsvariabele QGIS_SERVER_API_RESOURCES_DIRECTORY te wijzigen.

Een typische installatie voor Linux zal de volgende boom voor de mappen hebben:

/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

U kunt, om de sjablonen te overschrijven. de gehele boom kopiëren naar een andere locatie en QGIS_SERVER_API_RESOURCES_DIRECTORY laten verwijzen naar de nieuwe locatie.