Als productowner wil ik dat de testvoorziening standaard functionaliteit biedt om te checken of een API voldoet aan de NL API Strategie

[HenriKorver]

zodat we snel een eerste beeld hebben van de kwaliteit van de API.

Toelichting: Het checken of een API voldoet aan de design rules van de NL API Strategie is van andere aard dan testen van een API tegen een Postman collection die de API valideert op correct gedrag, Dat laatste gebeurt op runtime niveau waarbij http-requests en json bodies worden gecontroleerd. Voor het checken van de NL design rules ligt het meer voor de hand om het OAS schema te inspecteren.

Oplossingsrichting: Hieronder een aantal checks die (makkelijk) te automatiseren zijn:

• Aanwezigheid van een OAS schema via pad http(s)://.../api/.../schema/openapi.json
• OAS schema heeft versie 2.0 of hoger
• OAS schema valideert
• Correcte vulling van header API-version
• Aanwezigheid van mediatypes zoals application/JSON of/en application/JSON+HAL (API-28, API-29)
• Indien geo van toepassing is, dan aanwezigheid van content negotiation voor het coördinaatreferentiestelsel (API 43-46)
• API’s ondersteunen JSON gecodeerde POST, PUT en PATCH payloads (API-33)
• Pretty print is standaard uitgeschakeld (API-31)
• Filter query-parameters zijn gelijk aan de velden waarop gefilterd kan worden (API-34)
• Voor sorteren wordt de query-parameter sorteer gebruikt (API-35)
• Voor vrije-tekst zoeken wordt een query-parameter zoek gebruikt (API-36)
• Foutafhandeling is gestandaardiseerd (API-50).
  • API’s ondersteunen de gestandaardiseerde foutmeldingen van de HTTP-statuscodes 400 en 500 reeks inclusief een verwerkbare JSON representatie in lijn met RFC7807.
• API’s passen de verplichte HTTP-statuscodes toe (API-51)
  • De volgende http-statuscodes worden minimaal toegepast: 200, 201, 204, 304, 400, 401, 403, 405, 406, 409, 410, 415, 422, 429, 500, 503.
• API-endpoints dienen géén trailing slashes te bevatten (API-52).
  • URIs die gebruikt worden om collecties van resources of individuele resources op te vragen eindigen nooit met een trailing slash. Een resource leeft op één plek/path. Resource paths eindigen zonder slash.

Niet alle API design rules zijn (eenvoudig) te automatiseren. Bijvoorbeeld het checken of resourcenamen zelfstandige naamwoorden zijn in meervoud zijn geschreven.

Voor een overzicht van alle NL API design rules zie https://geonovum.github.io/KP-APIs/#bijlagen.

Definition of ready

• [ ] Iedereen in het team begrijpt de user story
• [ ] Is klein genoeg (maximaal 1/3 van sprint)
• [ ] Product Owner akkoord en voorzien van prioriteit (mag alleen afgevinkt worden door Henri)
• [ ] Voorzien van Acceptatiecriteria (duidelijk en testbaar)
• [ ] Voorzien van Definition of Done (duidelijk en testbaar)
• [ ] Voorzien van taken
• [ ] Idee hebben van hoe deze user story kan worden gedemonstreerd.
• [ ] Vastgelegd in Github en geplaatst in kolom ready

Definition of done algemeen

• [x] Functionaliteit aanroepbaar via user interface
• [x] Functionaliteit aanroepbaar via API

Definition of done specifiek voor deze user story

• [ ] ....

Acceptatiecriteria

• [ ] ...
• [ ] ...
• [ ] ...

Taken Taken worden apart uitgewerkt in issues.

[HenriKorver]

Geonovum werkt ook aan een OpenAPI inspectietool: https://geonovum.github.io/oas-verkenning. Het is aan te roepen als API: https://rebilly.github.io/ReDoc/?url=https://geonovum.github.io/oas-verkenning/assets/openapi.yaml&nocors.

Voor nu werkt het alleen voor OAS 2 versies:

En niet voor OAS 3:

Als dit tool voldoende goed werkt kunnen we het wellicht integreren met die van ons