search

VNG-Realisatie / gemma-zaken

Samen ontwikkelen van API's voor Zaakgericht werken
https://vng-realisatie.github.io/gemma-zaken/
Other
41 stars 27 forks source link

Als gemeente wil ik dat de ZDS-standaard de API- en URI-strategie van DSO volgt #216

Closed Hugo-ter-Doest closed 5 years ago

Hugo-ter-Doest commented 6 years ago

...zodat API's op een uniforme manier worden aangeboden en URI's op een uniforme manier bronnen ontsluiten.

Motivatie voor deze user story is dat we hebben afgesproken dat ZDS 2.0 moet voldoen aan de API- en URI-strategie van DSO.

Definition of ready

Definition of done

Acceptatiecriteria

Taken

Hugo-ter-Doest commented 6 years ago

Checklist voor de API-strategie van DSO

Bron: Deelprogramma Digitaal Stelsel Omgevingswet - Kaderstellende notities API-strategie Versie 1.1 Vastgesteld 12-03-2018

Nummer Kader ZDS 2.0 voldoet Uitleg
API-01 Bestaande API’s voldoen waar mogelijk aan de API-strategie N.v.t. ZDS 2.0 bevat nieuwe API's.
API-02 Product- en leverancier-specifieke API’s worden nooit direct aangeroepen N.v.t De referentie-implementatie van ZDS 2.0 roept geen product- of leverancier-specifieke API's aan.
API-03 API’s garanderen dat operaties “Veilig” en/of “Idempotent” zijn Ja
API-04 Toestandsinformatie wordt nooit op de server opgeslagen ja
API-05 Communicatie met API’s verloopt alleen via het Stelselknooppunt N.v.t. Het Stelselknooppunt is alleen bedoeld voor de API's t.b.v. de Omgevingswet. ZDS 2.0 wordt breder ingezet.
API-06 Alleen standaard HTTP-operaties worden toegepast Ja
API-07 Definitie van het koppelvlak is in het Nederlands tenzij er sprake is van een officieel Engelstalig begrippenkader Ja
API-08 Resource namen zijn zelfstandige naamwoorden in het meervoud Ja
API-09 Relaties van geneste resources worden binnen het eindpunt gecreëerd Nee Informatieobjecten (documenten) hebben een n-op-1 relatie met zaken. Informatieobjecten zijn een geneste resource, maar hebben wel een eigen endpoint.
API-10 Resources ondersteunen “lazy” en “eager” laden van relaties Ja In ZDS worden relaties met links gelegd. Eager laden wordt mogelijk gemaakt met de expand query-parameter.
API-11 Gelinkte resources worden expliciet en selectief mee-geladen Ja Dit mechanisme wordt mogelijk gemaakt met de expand query-parameter.
API-12 Representatie op maat wordt ondersteund Nog niet Is een globale configuratie/programmatie, dus niet afhankelijk van specifieke endpoint. T.z.t. moeten we hier een user story voor klaarmaken.
API-13 Acties die niet passen in het CRUD model worden een sub-resource Ja
API-14 De verbinding is ALTIJD versleuteld met minimaal TLS V1.2 Ja Via NLX
API-15 API’s zijn alleen bruikbaar met behulp van een API-key Nog niet Wordt uitgewerkt met OAUTH2
API-16 Tokens worden niet gebruikt in query parameters Nog niet Wordt uitgewerkt met HTTP Headers
API-17 Autorisatie is gebaseerd op OAuth 2.0 Nog niet Wordt uitgewerkt
API-18 Authenticatie voor API’s met toegangsbeperking of doelbinding is gebaseerd op PKIoverheid Nee We gaan er (voorlopig) van uit dat dit door een knooppunt wordt opgelost.
API-19 Documentatie is gebaseerd op OAS 2.0 of hoger Ja Documentatie is gebaseerd op OAS 3.0
API-20 Documentatie is in het Nederlands tenzij er sprake is van bestaande documentatie in het Engels of er sprake is van een officieel Engelstalig begrippenkader Ja
API-21 Documentatie wordt getest en geaccepteerd Ja
API-22 Wijzigingen worden gepubliceerd met een uitfaseringschema Ja Onder verantwoordelijkheid van VNG Realisatie
API-23 De overgangsperiode bij een nieuwe API versie is maximaal 1 jaar Ja Bij breaking changes
API-24 Alleen het major versienummer is onderdeel van de URI Ja
API-25 Gebruikers van een ‘deprecated’ API worden actief gewaarschuwd Nee
API-26 JSON first - API’s ontvangen en versturen JSON Ja Echter voorlopig enkel application/json geimplementeerd
API-27 API’s zijn optioneel voorzien van een JSON Schema Nee Voorlopig niet. OpenAPI 3.0 doet hier al heel veel, JSON Schema laat toe om validatieregels in meer detailen te specifieren.
API-28 Content negotiation wordt volledig ondersteund Ja
API-29 API’s controleren dat de Content-Type header is ingesteld In ontwikkeling Aanzet gemaakt, nog niet klaar
API-30 Woorden in veldnamen zijn gedefinieerd in camelCase Ja
API-31 Pretty print is standaard uitgeschakeld Ja
API-32 Een JSON-response heeft geen omhullende envelop Ja
API-33 API’s ondersteunen JSON gecodeerde POST, PUT en PATCH payloads Ja
API-34 Filter query-parameters zijn gelijk aan de velden waarop gefilterd kan worden Nee Filtering nog niet geimplementeerd, later toetsen
API-35 Voor sorteren wordt de query-parameter sorteer gebruikt In ontwikkeling Nog niet geimplementeerd, config wel gedaan
API-36 Voor vrije-tekst zoeken wordt een query-parameter zoek gebruikt In ontwikkeling Nog niet geimplementeerd, config wel gedaan
API-37 API’s die vrije-tekst zoeken ondersteunen kunnen overweg met twee soorten wildcard karakters: * en ? Nog niet
API-38 GEO API’s ontvangen en versturen GeoJSON Ja
API-39 GeoJSON is onderdeel van de embedded resource in de JSON response Ja API-strategie-document zou een voorbeeld kunnen gebruiken, dit is wat onduidelijk geformuleerd.
API-40 Voor GEO queries is een POST end-point beschikbaar Nog niet
API-41 POST end-points zijn uitbreidbaar voor gecombineerde vragen Nog niet
API-42 Resultaten van een globale geometrische zoekvraag worden in de relevante geometrische context geplaatst ? API-strategie is niet duidelijk
API-43 Het voorkeur-coördinatenstelsels (CRS) is ETRS89, maar het CRS wordt niet impliciet geselecteerd Nee WGS84 wordt momenteel als default gebruikt voor gemak met client libraries
API-44 Het coördinatenstelsel (CRS) van de vraag en het antwoord wordt in de header meegestuurd Nee Zie API-43
API-45 Het gewenste coördinatenstelsel wordt op basis van content negotiation overeengekomen Nee Zie API-43
API-46 Paginering wordt gerealiseerd op basis van JSON+HAL Nee Omdat HAL nog niet goed wordt ondersteund door het gebruikte framework.
API-47 Waar relevant wordt caching toegepast Ja
API-48 Beperken van het aantal verzoeken per tijdsperiode wordt centraal opgelost door het Stelselknooppunt N.v.t. Nog niet bekend of en via welk knooppunt ZDS API's worden aangeboden.
API-49 Begrenzingen worden proactief gemeld Nog niet Er is (nog) geen rate-limiting ingesteld. Indien dit via een knooppunt verloopt, dan zal het knooppunt ook deze headers toevoegen in plaats van onze referentiecomponent.
API-50 Foutafhandeling is gestandaardiseerd Ja
API-51 API’s passen de verplichte HTTP-statuscodes toe Ja
Hugo-ter-Doest commented 6 years ago

Checklist voor de URI-strategie van DSO

Bron: Deelprogramma Digitaal Stelsel Omgevingswet, Kaderstellende notities, URI-strategie, Versie 1.1 Vastgesteld 12-03-2018

Nummer Kader ZDS 2.0 voldoet Uitleg
URI-01 De basisopbouw van URI’s volgt internetstandaard RFC3986
URI-02 In de basisopbouw van URI zijn de onderkende resourcecategorieën duidelijk herkenbaar
URI-03 De URI van een webpagina specificeert optioneel een portaal ofwel een specifieke beveiligingscontext
URI-04 De URI van een webpagina identificeert het verantwoordelijke stelselonderdeel
URI-05 De URI van een webpagina identificeert de pagina binnen het stelselonderdeel
URI-06 De URI van een webpagina specificeert optioneel een reeks query-parameters
URI-07 De URI van een webpagina specificeert optioneel een fragment binnen de pagina
URI-08 De URI van een SOAP web-service specificeert een expliciete beveiligingscontext N.v.t.
URI-09 De URI van een SOAP web-service identificeert het verantwoordelijke stelselonderdeel N.v.t.
URI-10 De URI van een SOAP web-service identificeert de service binnen het stelselonderdeel N.v.t.
URI-11 De URI van een SOAP web-service specificeert het major versienummer van de service N.v.t.
URI-12 De URI van een REST API specificeert een expliciete beveiligingscontext
URI-13 De URI van een REST API identificeert het verantwoordelijke stelselonderdeel N.v.t.
URI-14 De URI van een REST API identificeert de service binnen het stelselonderdeel
URI-15 De URI van een REST API specificeert het major versienummer van de API Ja
URI-16 De URI van een REST API identificeert de collectie binnen het stelselonderdeel N.v.t.
URI-17 De URI van een REST API specificeert optioneel een verwijzing
URI-18 De URI van een REST API specificeert optioneel een reeks query-parameters
URI-19 De URI van linked-data identificeert het DSO-domein van een resource
URI-20 De URI van linked-data identificeert optioneel een pad om lokale informatie te onderscheiden
URI-21 De URI van linked-data specificeert het type URI
URI-22 De URI van linked-data specificeert een vocabulaire
URI-23 De URI van linked-data identificeert de collectie binnen de resource
URI-24 De URI van linked-data specificeert optioneel een verwijzing
URI-25 De URI van linked-data specificeert per vocabulaire tevens een klassenaam of eigenschapsnaam
URI-26 Omgevingsloket URI’s definiëren de autoriteit binnen het hoofddomein N.v.t.
URI-27 Stelselknooppunt URI’s definiëren de autoriteit binnen het sub-domein service N.v.t.
URI-28 Linked-data URI’s definiëren de autoriteit binnen afzonderlijke sub-domeinen
URI-29 URI’s definiëren optioneel de staging-omgeving binnen de autoriteit
URI-30 Slechts één stelselcomponent is verantwoordelijke voor het aanbieden van een resource
URI-31 Het Omgevingsloket zorgt voor de routering van inhoud (pagina’s) N.v.t.
URI-32 Het Stelselknooppunt zorgt voor de routering van service-verzoeken N.v.t. via NLX
URI-33 URI’s definiëren optioneel een expliciete beveiligingscontext
URI-34 Een domein binnen een URI is een strikt functionele identificatie
URI-35 Het Stelselknooppunt zorgt voor de routering op basis van domeinen N.v.t.
URI-36 De URI van een linked-data resource specificeert optioneel een reeks query-parameters
URI-37 URI’s voldoen aan de algemene afspraken
URI-38 URI’s voor informatie voldoen aan de daarvoor geldende afspraken
URI-39 URI’s voor begrippen voldoen aan de daarvoor geldende afspraken
sergei-maertens commented 6 years ago

API strategie

URL strategie Ik zag geen vraagtekens :-)

Hugo-ter-Doest commented 6 years ago

Thanks, ik verwerk het. URI-strategie volgt nog.

joeribekker commented 6 years ago

Nice gedaan Hugo!

Technisch zijn er ook een aantal testbaar. We hebben voor het ZTC van Haarlem per DSO API-richtlijn een test geschreven: https://github.com/maykinmedia/zaaktypecataloguscomponent/blob/develop/src/ztc/api/tests/test_api_strategy.py

Het uitgangspunt van de DSO is op sommige punten wel echt anders, voornamelijk waar het het knooppunt betreft waar sommige zaken worden "opgelost". Dit knooppunt is een beetje tegenstrijdig met de wens om componenten ook niet centraal aan te bieden (dat is zelfs de eerste stap).

HenriKorver commented 6 years ago

Volgende week is de tweede bijeenkomst van de werkgroep NL API Strategie waar ik VNG-R zal vertegenwoordigen. Zijn er vanuit deze groep wensen of vragen die ik daar zou kunnen inbrengen?

Ter inspiratie: hieronder de vragen die worden gesteld vanuit de werkgroep BRP-bevragingen.

sergei-maertens commented 6 years ago

@HenriKorver het lijkt me zeer handig om even de designkeuzes na te lopen en te kijken wat daarvan terug kan naar de DSO om formeel vast te leggen! Zie https://github.com/VNG-Realisatie/gemma-zaken/blob/master/docs/content/developers/design-keuzes.md

Een aantal van mijn standpunten/vragen samengevat:

sergei-maertens commented 6 years ago

@joeribekker vroegen wij ons ook niet af of er hier effectief ontwikkelaars bij aansluiten op die meeting die ook APIs bouwen/consumen?

TCIMEddy commented 5 years ago

Opgenomen in acceptatiecriteria dus geen aparte User Story om op te pakken wel een mooie checklist