search

Geonovum / KP-APIs

26 stars 40 forks source link

Is het mogelijk om met een OGC-API Features service te voldoen aan nl-api strategie #425

Open pvgenuchten opened 2 years ago

pvgenuchten commented 2 years ago

Een placeholder voor een onderzoek om te zien of een OGC-API Features service zodanig in te richten is zodat deze aan de nl api strategie voldoet.

OGC API Features is een standaard uit het geodomein welke enkele overeenkomsten met de nl api strategie heeft. Door beide te combineren kunnen organisaties er in gevallen voor kiezen met 1 implementatie beide gebruikersgroepen te bedienen.

Daar waar het wringt kunnen we mogelijk richting api-strategie, dan wel OGC, wijzigingsvoorstellen doen om beter op elkaar aan te sluiten.

pvgenuchten commented 2 years ago

Overigens geldt dit aspect ook voor andere OGC API's; Records, Coverages, Tiles, Processes, EDR

lvdbrink commented 2 years ago

Op een aantal punten is het niet mogelijk om met een OGC API Features ook aan de API strategie te voldoen. Eén daarvan is de manier waarop je data in een bepaald CRS opvraagt en terugkrijg.

Hierover zijn er nieuwe inzichten uit het recente Geonovum API testbed: ik hoorde in de eindpresentatie de suggestie dat het triviaal is om in een API zowel de NL API strategie als OGC API Features te ondersteunen, in ieder geval wat betreft het CRS onderdeel; en dat je dan de oude NL API strategie CRS aanbevelingen op termijn uit zou kunnen faseren.

Uit het rapport van testbed topic 1, dat ging over CRS in OGC APIs en is uitgevoerd door GIS Specialisten:

The request headers are used to specify a media type. [...] With URI pattern content negotiation, a different resource is requested from the server. [...] The nature of spatial data more closely represents the pattern of different resources, than of different media types. Therefore we support the OGC decision to implement the content-negotiation through the URI pattern.

In addition to the stated benefits, the URI pattern also makes the API more human and search engine readable, since it allows for simply browsing the available paths for different encodings and projections in the browser. This allows for greater findability of the data and to greater usage.

Given the considerations, we recommend following the OGC method of implementing content-negotiation. Technically, it is trivial to implement either way. For existing API's or to be able to support clients that can only do request headers, it might be feasible to start supporting both methods, to allow for an upgrade period, after which only the URI pattern method will be supported.

Mijn voorstel is om in de volgende versie van de geo-extensie beide methoden om CRS op te vragen te ondersteunen, met daarbij de opmerking dat de 'oude' NL API strategie methode op termijn wordt uitgefaseerd. Ik hoor graag de mening van anderen hierover.

strijm commented 2 years ago

Bovenstaande voorstel lijkt mij een prima manier om de migratie van de huidige manier van CRS negotiation naar een nieuwe manier daarvan te ondersteunen. Om het voor gebruikers uiteindelijk eenduidiger en eenvoudiger te maken is het goed om zoveel mogelijk aan te sluiten bij de OGC API Features standaard. Het gebruik van het URI pattern lost in ieder geval al een discussie op m.b.t. het gebruik van HTTP foutcodes (415 en 406).

fterpstra commented 2 years ago

Belangrijk om hierbij in gedachte te houden is dat de oorspronkelijke Geo extensie nooit is vastgesteld. Dat is altijd een draft geweest met gevarendriehoek dat hij ieder moment kan veranderen. Het is wel zo dat de methode voor CRS uit de Geo extensie ook door het DSO is gebruikt in hun wel vastgestelde API strategie. dus binnen het DSO heeft het mechanisme wel status. Verder natuurlijk een met voorgestelde aanpassing

lvdbrink commented 2 years ago

Tijdens werkgroepoverleg akkoord van aanwezigen.

pvgenuchten commented 2 years ago

Suggestie om het issue over crs negotiation als een apart issue op te nemen, en dit issue te gebruiken om een overzicht van alle uitdagingen op dit vlak te houden, dan wel een issue categorie voor dit type issues aan te maken. Mogelijk interessant om issues te splitsen in:

een voorbeeld waar nl strategie strenger is:

API-57 | Return the full version number in a response header

lvdbrink commented 2 years ago

Suggestie om het issue over crs negotiation als een apart issue op te nemen

Gedaan, zie #432

lvdbrink commented 2 years ago

Nadere analyse van de OGC API Features standaard is nodig. Voorstel werkwijze:

Inventariseer de API regels in OGC API Features part 1 en part 2 en maak voor elke requirement die specifiek over geofunctionaliteit gaat maar nog niet in de API strategie staat, een issue aan. In elk van die issues kunnen we dan bediscussiëren of we die specifieke requirement willen overnemen en dan de taak aan een werkgroeplid toewijzen.

Zo maken we als eerste stap de NL API strategie geo-extensie conform OGC API Features.

Vervolgens kunnen we ervoor kiezen de scope te verbreden en ook te gaan kijken naar niet-geo-specifieke requirements van OGC API Features, en hoe die verschillen van de NL API strategie.

Het toevoegen van requirements uit Part 3: Filtering en eventueel Part 4: Create, Replace, Update and Delete moet een bredere discussie zijn met de ADR werkgroep als geheel.

lvdbrink commented 2 years ago

Pieter neemt part 2 door.

Mark en Linda verdelen part 1.

We inventariseren de geo-functionaliteiten om deze eventueel over te nemen in de geo-extensie.

We inventariseren ook de niet-geo requirements die andere delen van de API strategie raken. Met behulp van deze inventarisatie kunnen we de oorspronkelijke vraag van dit issue beantwoorden.

lvdbrink commented 2 years ago

Ik heb een deel van OGC API Features part 1 doorgenomen en in een tabel een overzicht gemaakt van de OGC requirement vs de API strategie. Geconcentreerd op geo-functionaliteit. Bredere functionaliteit ook genoemd maar nog niet geconfronteerd met huidige API strategie.

Toelichting tabel:

Conformance class Beschrijving Opnemen ja/nee Geo of breder Status Toelichting
/req/core/root-op GET operation at / tbd breder tbd -
/req/core/root-success HTTP 200 teruggeven tbd breder tbd -
/req/core/api-definition-op GET operation op API definities tbd breder tbd -
/req/core/api-definition-success definitie teruggeven in gevraagde media type tbd breder tbd -
/rec/core/api-definition-oas OAS 3.0 tbd breder tbd -
/req/core/conformance-op GET operation at /conformance tbd breder tbd -
/req/core/conformance-success HTTP 200 teruggeven tbd breder tbd -
/req/core/http Voldoen aan HTTP 1.1 tbd breder tbd -
/rec/core/head HEAD method ondersteunen tbd breder tbd -
- Geen restricties op HTTP/HTTPS breder tbd -
/req/core/query-param-unknown 400 teruggeven bij onbekende param tbd breder tbd -
/req/core/query-param-invalid 400 teruggeven bij invalid param value tbd breder tbd -
/rec/core/etag entity tags ondersteunen tbd breder tbd -
/rec/core/cross-origin cross-origin requests ondersteunen tbd breder tbd -
/rec/core/html HTML encoding ondersteunen tbd breder tbd -
/rec/core/geojson GeoJSON encoding ondersteunen ja geo opgenomen -
/rec/core/string-i18n meertaligheid via HTTP mechanismen tbd breder tbd -
/req/core/crs84 CRS84 als default CRS ja geo niet opgenomen API-40 noemt ETRS89 als default. De volgorde van de assen bij CRS84 is lat-long, terwijl ETRS89 de volgorde long-lat hanteert.
/rec/core/link-header HTTP link headers gebruiken tbd breder tbd -
/req/core/fc-md-op GET operation at /collections breder opgnomen Opgenomen in geo-extensie als onderdeel van ondersteuning CRS
/req/core/fc-md-success HTTP 200 teruggeven tbd breder tbd -
/req/core/fc-md-links self en alternate links tbd breder tbd -
/rec/core/fc-md-descriptions meer over links tbd breder tbd -
/rec/core/fc-md-license link naar gebruikslicentie tbd breder tbd -
/req/core/fc-md-items feature collections ja geo opgenomen -
/req/core/fc-md-items-links link naar elke encoding tbd breder tbd -
/req/core/fc-md-extent ruimtelijke en temporele extent opnemen ja geo niet opgenomen Het valt wel onder hfd 7.13 van OAF, waar we al naar verwijzen in de geo-extensie. Maar dit is in het kader van CRS. Het zou goed zijn om deze extent property expliciet te noemen.
/rec/core/fc-md-extent-single enkele temporele en ruimtelijke extent ja geo niet opgenomen idem
/req/core/sfc-md-op GET operation at /collections/{collectionId} ja geo niet opgenomen Feature collections zijn essentieel voor geo-apis. Daarom goed om dit wel op te nemen. We kunnen dit in algemene zin doen door naar heel OAF 7.13 en 7.14 te verwijzen.
/req/core/sfc-md-success HTTP 200 teruggeven tbd breder tbd -
pvgenuchten commented 2 years ago

Ha Linda, mooie start. Ik had de analyse eigenlijk andersom verwacht, de eisen van api strategie benoemen en dan vast stellen of de eis in te vullen is met ogc api. Een verdere uitwerking van wat we ook in het testbed gedaan hebben: https://apitestdocs.geonovum.nl/cases/api_rules/

PB-GNM commented 2 years ago

Een mooi overzicht. Ik heb net als Linda ook gekeken vanuit de de conformance class vanuit de OGC API Features, maar dan part 2.

Eigenlijk kwam veel al overeen en heb ik alleen opgeschreven wanneer het niet overeen kwam. Dat heb ik hieronder gezet in dezelfde structuur als Linda heeft gedaan.

CC-nr Conformance class Beschrijving Opnemen ja/nee Geo of breder Status Toelichting
req3 /req/crs/fc-md-storageCrs If all features in a spatial feature collection are stored using a particular CRS then the property storageCrs SHALL be specified in the collection object of the spatial feature collection to indicate the identifier for this storage CRS. tbd geo niet opgenomen kan handig zijn om transformaties te voorkomen
rec2 /rec/crs/fc-md-coordinateEpoch If the storage CRS of the spatial feature collection is a dynamic coordinate reference system, the property storageCrsCoordinateEpoch in the collection object of the spatial feature collection SHOULD provide the coordinate epoch of the coordinates. tbd geo niet opgenomen nodig als de epoch van toepassing is
req4 /req/crs/fc-md-storageCrs-valid-value The value of the storageCrs property SHALL be one of the CRS identifiers from the list of supported CRS identifiers found in the collection object using the crs property. tbd geo niet opgenomen lijkt mij vrij evident
req8 /req/crs/fc-bbox-crs-valid-defaultValue If the bbox-crs parameter is not specified then the coordinate values of the bbox parameter SHALL be assumed to be in the default CRS specified in OGC API - Feature - Part 1: Core; tbd geo niet opgenomen Het in Part1 is onduidelijk hoe je de default aangeeft. Het zegt: the first CRS is the default coordinate reference system, maar ook WGS84 en WGS84h
req12 //req/crs/fc-crs-default-value If the crs parameter is not specified then the coordinate values of the bbox parameter SHALL be assumed to be in the default CRS specified in OGC API - Feature - Part 1: Core; tbd geo Er staat nu Define a default CRS in the API, if the consumer does not specify the CRS it is assumed it uses the default. Het is in Part 1 onduidelijk hoe je de default aangeeft. Het zegt: the first CRS is the default coordinate reference system, maar ook WGS84 en WGS84h
req15 /req/crs/ogc-crs-header An HTTP header named Content-Crs SHALL be used to assert the coordinate reference system used in the body of a response. tbd geo Staan nog fout in API-45 -
req7 en 11 /req/crs/fc-bbox-crs-valid-value en /req/crs/fc-crs-valid-value If the value of the (bbox-)crs parameter is not one of the CRS identifiers from the list of supported CRS identifiers, then the server SHALL respond with the HTTP status code 400. tbd geo nog niet in de extensie opgenomen Maar misschien staat dit al elders in het hoofddocument?
lvdbrink commented 2 years ago

Verdere analyse van OGC API Features part 1: paragraaf 7.15 Features

Conformance class Beschrijving Opnemen ja/nee Geo of breder Status Toelichting
/req/core/fc-op GET operation of items tbd breder tbd -
/req/core/fc-limit-definition limit parameter tbd breder tbd -
/req/core/fc-limit-response-1 correct response to limit tbd breder tbd -
/req/core/fc-bbox-definition bbox parameter ja geo opgenomen -
/req/core/fc-bbox-response correct response to bbox ja geo opgenomen -
/req/core/fc-time-definition datetime parameter nee breder tbd Zie hfd 11 Temporal
/req/core/fc-time-response correct response to datetime parameter nee breder tbd -
/req/core/fc-response HTTP 200 response on success ja breder opgenomen -
/req/core/fc-links Include link to self tbd breder tbd -
/req/core/fc-rel-type Include rel and type on links tbd breder tbd -
/req/core/fc-timeStamp timeStamp on response tbd breder tbd -
/req/core/fc-numberMatched numberMatched on response tbd breder tbd -
/req/core/fc-numberReturned numberReturned on response tbd breder tbd -
/req/core/fc-timeStamp timeStamp on response tbd breder tbd -
lvdbrink commented 2 years ago

Verdere analyse van OGC API Features part 1: paragraaf 7.16 Feature, hfd 8. Encodings, en hfd 9. OpenAPI 3.0

Conformance class Beschrijving Opnemen ja/nee Geo of breder Status Toelichting
/req/core/f-op GET operation of feature tbd breder tbd -
/req/core/f-success HTTP 200 response on success ja breder opgenomen in algemene zin opgenomen
/req/core/fc-links Include link to self, other media types and collection tbd breder tbd -
/req/html/definition Support media type text/html tbd breder tbd -
/req/html/content Req on content of HTML body tbd breder tbd -
/req/geojson/definition Support GeoJSON how to Ja geo opgenomen Nog wel verwijzing naar deze requirement opnemen in API-34
/req/geojson/content Req on content of GeoJSON response Ja geo tbd Als uitbreiding opnemen bij API-34
/req/gmlsf0/definition Support GML 3.2 SF0 tbd geo tbd Hoeven we m.i. niet expliciet op te nemen als API rule. GML staat wel genoemd in Note over andere formaten naast GeoJSON.
/req/gmlsf0/content Req on content of GML response tbd geo tbd -
/req/gmlsf0/headers req on properties in header of GML response tbd geo tbd -
/req/gmlsf2/definition Support GML 3.2 SF2 tbd geo tbd Zelfde als gmlsf0, maar dan voor simple features level 2.
/req/gmlsf2/content Req on content of GML SF2 response tbd geo tbd -
/req/gmlsf2/headers req on properties in header of GML SF2 response tbd geo tbd -
/req/oas30/oas-definition-1 Links to API definition in response tbd breder tbd -
/req/oas30/oas-definition-2 Be conformant to OpenAPI 3.0 tbd breder opgenomen API-16, API-51
/req/oas30/oas-impl Implement all OAS capabilities tbd breder opgenomen API-16, hoewel dit wel specifieker is gesteld in OGC API
/req/oas30/completeness Completeness of API definition tbd breder tbd -
/req/oas30/exceptions-codes HTTP status codes for exceptions tbd breder opgenomen staat verspreid over ADR beschreven, maar staat er wel in.
/req/oas30/security Documentation of security scheme in OA definition tbd breder tbd - lijkt er niet in te staan
/rec/oas30/f-key-properties Key feature properties in response schema tbd breder tbd - lijkt er niet in te staan

Hiermee is de inventarisatie compleet.

lvdbrink commented 2 years ago

Samenvatting van wat nog te doen is op basis van bovenstaande tabellen:

Uit OGC API Features part 1 Core:

Conformance class Beschrijving Toelichting
/req/core/crs84 CRS84 als default CRS API-40 noemt ETRS89 als default. De volgorde van de assen bij CRS84 is lat-long, terwijl ETRS89 de volgorde long-lat hanteert.
/req/core/fc-md-extent ruimtelijke en temporele extent opnemen Het valt wel onder hfd 7.13 van OAF, waar we al naar verwijzen in de geo-extensie. Maar dit is in het kader van CRS. Het zou goed zijn om deze extent property expliciet te noemen.
/rec/core/fc-md-extent-single enkele temporele en ruimtelijke extent. Zoals vorige punt.
/req/core/sfc-md-op GET operation at /collections/{collectionId}. Feature collections zijn essentieel voor geo-apis. Daarom goed om dit wel op te nemen. We kunnen dit in algemene zin doen door naar heel OAF 7.13 en 7.14 te verwijzen.
/req/geojson/definition Support GeoJSON. Al opgenomen, maar nog wel verwijzing naar deze requirement en/of recommendation /rec/core/geojson opnemen in API-34.
/req/geojson/content Requirement on content of GeoJSON response. Als uitbreiding opnemen bij API-34
/req/gmlsf0/definition Support GML 3.2 SF0 Hoeven we m.i. niet expliciet op te nemen als API rule, maar wel naar verwijzen in de Note over andere formaten naast GeoJSON, waar GML genoemd staat.
/req/gmlsf2/definition Support GML 3.2 SF2 Zelfde als vorige. In de note verwijzen naar beide simple features levels (0 en 2).

Uit OGC API Features part 2 CRS:

Conformance class Beschrijving Toelichting
/req/crs/fc-md-storageCrs property voor CRS waarin de data is opgeslagen Kan handig zijn om transformaties te voorkomen.
/rec/crs/fc-md-coordinateEpoch Epoche van opgeslagen coordinaten Nodig als de epoch van toepassing is. Dit kan relevant zijn, zie handreiking CRS. Deze beide properties aan één ADR rule koppelen: 'be clear about storage CRS' oid.
/req/crs/fc-md-storageCrs-valid-value storageCRS moet 1 van de ondersteunde CRS zijn Vrij evident, maar kan geen kwaad om te noemen bij voorgaande ADR rule over storageCRS.
/req/crs/fc-bbox-crs-valid-defaultValue Als bbox-crs parameter ontbreekt uitgaan van default CRS Noemen bij bbox-crs ADR rule.
/req/crs/fc-crs-default-value Als crs parameter ontbreekt uitgaan van default CRS Noemen bij crs ADR rule.
/req/crs/ogc-crs-header Content-Crs header Zou nog fout staan in API-45. Dit komt nog uit de oude geo-extensie. Dit corrigeren we niet maar laten we voorlopig staan als deprecated regel.
/req/crs/fc-bbox-crs-valid-value en /req/crs/fc-crs-valid-value 400 code bij invalid value of (bbox-)crs parameter dit staat ook nog niet in algemene zin in de ADR, dus toevoegen bij de tekst over deze parameters.

Ik ga aan een PR hiervoor werken.

PB-GNM commented 2 years ago

Ik twijfel nog over de default CRS voor als de CRS niet opgegeven is als parameter en hink op 2 gedachten:

  1. Aan de ene kant denk ik dat voor Nederlandse gebruikers goed is om als default de storage CRS te nemen die dan bij voorkeur boven aan in de lijst van CRS-sen staat. De storage CRS presteert qua snelheid het beste en is het nauwkeurigst omdat er geen transformatie voor nodig is, want elke transformatie leidt tot extra onnauwkeurigheid. De storage CRS is in NL meestal RD (EPSG:28992) of ETRS89 (EPSG:4258). Alleen als de storage CRS niet gegeven is, dan is WGS84 met WGS84h de beste optie als default. Die zouden als aanbeveling dan wel in de CRS-lijst moeten staan.
  2. Aan de andere kant is aanpassen aan OGC-API Features Part 2 ook belangrijk, omdat de meeste applicaties dat verwachten. Dan moeten we toch vasthouden aan WGS84 met WGS84h als default wanneer er geen parameter wordt opgegeven. Dan moeten RD (EPSG:28992) of ETRS89 (EPSG:4258) naast WGS84 wel als aanbeveling in de lijst staan, maar die aanbeveling hebben we al.

Ik neig toch om het bij het laatste te houden en dan hoeven we ook het minste aan te passen, maar zou ook graag de mening van de anderen hier over horen. Dus dat is een onderwerp voor 21-6.

lvdbrink commented 2 years ago

Ik zelf vind ook aanpassen aan OGC API Features belangrijk en daarbij is WGS84 als default echt niet te vermijden. Ik heb in PR #452 hier tekst voor toegevoegd en ETRS89 als 'preferred' gehandhaafd.

lvdbrink commented 2 years ago

Te breed om nu op te pakken omdat je ook de API design rules buiten de geo-extensie gaat raken.