Dit document valt onder de volgende licentie:
Creative Commons Attribution 4.0 International Public License
Dit is een werkversie die op elk moment kan worden gewijzigd, verwijderd of vervangen door andere documenten. Het is geen door het Architecture Board goedgekeurde consultatieversie.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST en SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Het doel van deze standaard is om een afsprakenkader aan te bieden waar REST APIs binnen het Vlaams Data Integratie Platform (VDIP) aan moeten voldoen, met het oog op consistentie, interoperabiliteit en eenvoud voor implementatie en integratie van de API.
Dit is een collectie richtlijnen met als doel een eenvormigheid in een architecturale stijl te realiseren. Het is geen allesomvattende codex met gedetailleerde regels voor alle mogelijke problemen.
Naleven of uitleggen ('comply or explain') is een regelgevende benadering op het gebied van corporate governance en financieel toezicht. In plaats van bindende regels op te stellen, wordt een richtlijn opgesteld, die de teams kunnen naleven of, indien zij dat niet doen, publiekelijk uitleggen waarom zij dat niet doen.
Het doel van "naleven of uitleggen" is de teams te laten beslissen of een reeks normen geschikt is voor individuele softwareontwikkelingen binnen de context van het product waar ze aan werken. Aangezien een team mag afwijken van de norm, verwerpt deze aanpak de opvatting dat "one size fits all".
Als betrokken stakeholders, waaronder het Architectuur Board, de uitleg echter niet accepteren mag de afwijking van de norm niet worden geïmplementeerd.
De richtlijnen zijn opgebouwd in verschillende secties, elk gericht op een specifiek aspect van REST API-ontwerp en -ontwikkeling. Er is getracht een logische volgorde aan te houden om een geleidelijke verdieping te bieden, te starten van algemene principes voor API en REST design. Daarna de algemene richtlijnen over documentatie en API-ontwerp, gevolgd door richtlijnen rond gebruik van HTTP Headers, Foutenafhandeling en Beveiliging. Nadien wordt er dieper ingegaan op de inhoudelijke data formaten en vormvereisten (bijv. correct gebruik van standaard data typen, OSLO formaten, ...).
Deze standaard definieert normatieve REST design rules voor gesloten machine-to-machine gegevensuitwisseling tussen overheidspartijen binnen VDIP.
De sleutelwoorden MOET en MOETEN in dit document hebben een normatieve betekenis zoals beschreven in het Engels in [RFC2119] indien in hoofdletters geschreven.
In vergelijking met de SOA-WebService stijl van SOAP versus REST, is de eerste doorgaans gericht op operaties die meestal use-case-specifiek en gespecialiseerd zijn volgens een patroon van remote procedure calling. REST daarentegen is gericht op business (data-)entiteiten die als resources worden blootgesteld, geïdentificeerd via URI’s, en gemanipuleerd kunnen worden via gestandaardiseerde CRUD-achtige methoden met verschillende representaties en hypermedia.
RESTful API’s zijn doorgaans minder use-case-specifiek, hebben een minder strakke client/server-koppeling en zijn beter geschikt voor een ecosysteem van (kern)services die een API-platform bieden om uiteenlopende nieuwe businessservices op te bouwen. We passen RESTful webserviceprincipes toe op alle soorten (micro)servicecomponenten.
Een belangrijk principe voor API-ontwerp en -gebruik is Postel’s Law, aka "The Robustness Principle" (zie ook [RFC1122]):
Het Richardson maturiteitsmodel catalogeert de hoofdelementen van een RESTful interface in drie niveau’s. Om volledig in lijn te zijn met het REST uniform interface model van Roy Fielding moet aan alle niveau’s voldaan worden.
Resources. Omvat het opdelen van een service endpoint in resources die elk bepaald worden door een unieke URI
HTTP methods: Het gebruik van een standaard set van HTTP methods zodat vergelijkbare situaties op een uniforme manier behandeld worden zodat onnodige variaties vermeden worden
Hypermedia elementen: introduceert zelfbeschrijvende documentatie en vindbaarheid
VDIP REST API’s MOETEN minstens niveau 2 respecteren en proberen bij voorkeur ook te voldoen aan de voorwaarden van niveau 3.
Aanbevolen lectuur over RESTful API-ontwerp en service-architectuur:
API’s zijn volwaardige producten ('first class citizens') en dienen als dusdanig behandeld te worden. Het is een kern-product van het VDIP platform. Als organisatie willen we producten bouwen voor interne en externe afnemers die als een dienst kunnen geconsumeerd worden.
Platformproducten bieden hun functionaliteit via (publieke) API’s. Daarom hoort het ontwerp van API’s gebaseerd te zijn op het principe “API as a Product”:
Het omarmen van “API as a Product” bevordert een service-ecosysteem dat makkelijker kan evolueren en snel kan experimenteren met nieuwe businessideeën door kerncapaciteiten te hercombineren.
Begrijp de concrete use-cases van je klanten en weeg de ontwerpvarianten zorgvuldig af met een productmindset. Vermijd kortetermijnoptimalisaties in de implementatie als die onnodige verplichtingen aan clientzijde veroorzaken, en besteed veel aandacht aan API-kwaliteit en de developer experience voor de klanten.
“API as a Product” hangt nauw samen met het “API First”-principe (zie volgende sectie), dat meer focust op hoe hoogwaardige API’s engineeringmatig worden gerealiseerd.
API First is een belangrijk engineering- en architectuurprincipe. In essentie vraagt API First om twee zaken:
Door API’s buiten de code te definiëren, wordt vroege reviewfeedback mogelijk gemaakt en ontstaat een ontwikkelingsdiscipline die service-interfaceontwerp richt op:
Bovendien maken API-specificaties in een standaardformaat het volgende mogelijk:
Onderdelen van API First zijn ook deze API-richtlijnen en een gestandaardiseerd API-reviewproces om vroegtijdig feedback van peers en clientontwikkelaars te krijgen. Peer review is belangrijk om API’s van hoge kwaliteit te maken, architecturale en ontwerpafstemming mogelijk te maken, en ontwikkeling van clientapplicaties los te koppelen van de engineeringlevenscyclus van de serviceprovider.
Belangrijk is dat API First niet in conflict is met agile ontwikkelprincipes, maar dit complementeert. Serviceapplicaties horen incrementeel te evolueren, en hun API’s ook. De API-specificatie zal en moet iteratief evolueren in verschillende cycli; telkens startend met een draftstatus en vroege team- en peerreviewfeedback. API’s mogen veranderen en profiteren van implementatie-inzichten en feedback uit geautomatiseerde tests.
API-evolutie tijdens de ontwikkelcyclus kan breaking changes bevatten voor nog niet-productieve features, zolang wijzigingen met clients afgestemd zijn. API First betekent dus niet dat je 100% domein- en requirementbegrip moet hebben en nooit code mag schrijven voordat de volledige API is gedefinieerd en bevestigd via peer review.
Anderzijds is API First duidelijk in strijd met de slechte praktijk om API-specificaties pas te publiceren en om peer review te vragen nadat service-integratie, of zelfs productiegebruik, al gestart is. Vroege feedback vragen en krijgen is cruciaal: zo vroeg mogelijk, maar niet voordat API-wijzigingen voldoende samenhang en kwaliteit hebben (inclusief naleving van API-richtlijnen), al bevestigd via interne teamreviews.
VDIP REST API's MOETEN volgens het API first principe worden ontwikkeld.
case-id, application-id, information-request-id (niet dId, aId of iId)API First /core/api-first
Je MOET het API First-principe volgen, meer bepaald:
API scope /core/api-scope
Een API MOET een set resources bundelen die functioneel gerelateerd zijn en een autonome eenheid van business logic vormen.
API maturiteit /core/api-maturity
Alle REST APIs MOETEN minstens een Richardson maturiteitsmodel niveau 2 respecteren en proberen bij voorkeur ook te voldoen aan de voorwaarden van niveau 3.
Breek backward compatibility niet /core/backward-compatibility
Breek backward compatibility niet binnen een gepubliceerde major API-versie.
Vermijd onder meer:
Nieuwe functionaliteit MOET op een backwards compatibel manier toegevoegd worden (bijv. nieuwe optionele velden of endpoints).
Breaking changes vereisen een nieuwe major versie (bijv. /v2).
Richtlijnen zijn evolutief /core/guidelines-evolution
Deze richtlijnen evolueren over tijd. Een REST-dienst wordt ontwikkeld conform de versie van de richtlijnen die geldt op het moment van ontwikkeling.
x-guidelines-version (zie Versie van de richtlijnen documenteren).API Specificatie in OpenAPI /docs/api-spec-openapi
Elke API heeft een API specificatie document:
info object heeft een title en description veld)operation object van een path heeft een summary en description veld)securityScheme object van type oauth2 heeft een scopes veld met de correcte en volledige scope namen)Opmerking: Het gepubliceerde OpenAPI document is self-contained, het bronbestand mag verwijzen naar externe bestanden maar moet bij publicatie worden samengevoegd tot een self-contained document. Zie ook de regel Gebruik alleen duurzame en onveranderlijke externe referenties.
Opmerking: Bij het gebruik van Linked Data (JSON-LD, RDF, ...) kunnen er externe referenties gebruikt worden naar de informatie modellen, als deze een duurzame en onveranderlijke externe referentie zijn. Het verdient echter de aanbeveling om ook deze referenties in de API specificatie mee te publiceren.
Gebruik alleen duurzame en onveranderlijke externe referenties /docs/duurzame-referenties
Het gepubliceerde OpenAPI-document MOET op zichzelf staan, d.w.z. bestanden mogen geen verwijzingen bevatten naar lokale of externe inhoud, bijvoorbeeld ../fragment.yaml#/element of $ref: 'https://vdip.pages.vlaamseoverheid.ghe.com/specifications/rest/model/my-common-model.yaml#/schemas/Request'.
De reden hiervoor is dat de inhoud waarnaar extern wordt verwezen niet als duurzaam en niet onveranderlijk kan beschouwd worden.
Als gevolg hiervan kan de semantiek van een API op onverwachte manieren veranderen.
Het bronbestand mag tijdens ontwikkeling verwijzen naar externe bestanden, maar moet bij publicatie worden samengevoegd tot een self-contained document. Het wordt zelfs aanbevolen om externe referenties te gebruiken tijdens de ontwikkelcyclus van een API, om hergebruik van API-fragmenten mogelijk te maken en om de onderhoudbaarheid van de API-specificatie te verbeteren. Bv, de herbruikbare API-fragmenten van VDIP die beschikbaar zijn via: https://vdip.pages.vlaamseoverheid.ghe.com/specifications/rest/model/{model.yaml}
Schrijf APIs in de correcte taal voor het doelpubliek /docs/correct-taalgebruik-voor-api
Er wordt (waar nodig) gebruik gemaakt van het use-mention-onderscheid.
Business termen worden niet vertaald en blijven in originele taal van het informatie-model behouden, dit geldt in het bijzonder voor termen waar er geen correcte vertalingen voor zijn en die bv gebruikt worden in paden, parameters en body.
Gebruikersdocumentatie /docs/gebruikersdocumentatie
Naast de API-specificatie is het een best practice om ook een API-gebruikershandleiding aan te bieden. Dat verbetert de developer experience aan klantzijde, zeker voor engineers met minder ervaring met deze API. Een nuttige API-gebruikershandleiding beschrijft doorgaans de volgende aspecten:
De gebruikershandleiding moet online gepubliceerd worden, bijvoorbeeld via onze documentatiesite op Confluence. Vergeet niet om in de API-specificatie een link naar de API-gebruikershandleiding op te nemen via de #/externalDocs/url-property.
Metadata van de API beschrijven /docs/api-metadata
De volgende minimaal vereiste metadata over de API MOETEN worden beschreven in de OpenAPI-specificatie:
#/info/title een (unieke) identificerende, functionele beschrijvende naam van de API
#/info/description een duidelijke functionele beschrijving van de API
#/info/version de versie van de API specificatie, deze moet semantic versioning volgen
#/info/x-guidelines-version de versie van de REST Richtlijnen standaard tegen dewelke de dienst gebouwd wordt, deze moet semantic versioning volgen
#/info/contact/{name,url,email} contact info waar klanten terecht kunnen met vragen of problemen over de API
#/paths/{path}/{operation}/summary een korte functionele titel van de operatie, deze wordt aan de klant weergegeven in verschillende systemen
#/paths/{path}/{operation}/description een korte, duidelijke en begrijpelijke functionele beschrijving van de operatie
#/paths/{path}/{operation}/security/{scheme}/scopes een lijst van de OAuth scope(s) die vereist zijn voor deze API, met de correcte en volledige scope namen
#/components/securitySchemes/{scheme}/type er is een security scheme en het type MOET oauth2 zijn
#/components/securitySchemes/{scheme}/flows het security scheme MOET de juiste OAuth flow(s) bevatten, afhankelijk van het type client dat toegang tot de API nodig heeft (bijv. clientCredentials)
Versie van de richtlijnen documenteren /docs/guidelines-version
De OpenAPI-specificatie MOET via een extensie aangeven tegen welke versie van de VDIP REST-richtlijnen de API is ontwikkeld. Gebruik hiervoor het veld x-guidelines-version op het top-level info-object.
De waarde MOET de gepubliceerde versie van de richtlijnen zijn in semantic versioning formaat (bijv. "1.0.0").
Voorbeelden toevoegen aan OpenAPI /docs/voorbeelden
Voeg voorbeelden toe aan een OpenAPI-document.
Voorbeelden moeten worden opgegeven onder de OpenAPI-eigenschappen example of examples, en niet in een beschrijving.
examples maakt het mogelijk om meerdere voorbeelden op te geven, maar kan niet worden gebruikt binnen schema-definities.
Voorbeeldwaarden moeten schema-valid zijn.
Definitie van componenten /docs/components
Het dupliceren van definities (schema's, reacties, parameters, enz.) dient vermeden te worden.
Definieer ze liever één keer onder componenten, van waaruit ze kunnen worden aangeroepen (met $ref).
Alle componentnamen dienen in U.S. Engels worden gedefinieerd en de UpperCamelCase notatie gebruiken. Ook voor afkortingen geldt dat alle letters behalve de eerste in kleine letters moeten worden geschreven.
Gebruik geen underscores (_), koppeltekens (-) of punten (.) in een componentnaam, en gebruik geen cijfer als eerste letter.
| Onderdeel | Richtlijn |
|---|---|
| URL |
Een REST-URL wordt geformatteerd als {protocol}://{hostname}/{prefix}/{version}/{resource}/{identifier}.Gebruik geen hoofdletters in REST-URL's. |
| URL {prefix} | Een optionele pad prefix voor de REST diensten, te gebruiken wanneer dit nodig is om onderscheid te maken tussen andere type resources. |
| URL {hostname} | De hostname voor REST diensten is steeds de publieke API Gateway. |
| URL {protocol} |
Gebruik altijd HTTPS. Gebruik TLS 1.3 bij voorkeur, minimaal TLS 1.2. |
| URL {version} |
Neem de API-versie op in de URL. Noteer versies als kleine letter v gevolgd door een nummer (bijv. v1, v2, v14).Gebruik in de URL enkel major versies; minor/patch kan via header X-Version volgens semantic versioning: vMAJOR.MINOR.PATCH.
|
| URL {resource} |
Gebruik resource-namen in het meervoud. Gebruik binnen de URI geen resource-naam id, doc of ns.
|
| URL {identifier} |
Een resource-identifier is exact één unieke sleutel (eventueel samengesteld) die één resource identificeert. De sleutel moet semantisch coherent zijn: dezelfde sleutel verwijst door de tijd naar hetzelfde object. Gebruik geen URI als identifier in het pad. Gebruik bij voorkeur GUID's, long integers of stabiele domeinidentificatoren (zoals ISBN, CAPA key, rijksregisternummer). |
| URL formatting |
Gebruik geen fragmenten (#) in API-URL's.Gebruik geen underscores ( _) of punten (.) in resource-segmenten; gebruik koppeltekens (-).Gebruik geen betekenisvolle trailing slash ( /).Gebruik geen file-extensies als betekenisvol onderdeel van de REST-URL. |
Gebruik niet /api als basis pad /url/geen-api-basis-pad
Gebruik bij voorkeur de root (/) als base path voor publieke API-resources.
/api voegt meestal geen extra semantiek toe en leidt vaak tot redundantie in URL's.
Gebruik enkel een expliciet basispad als je meerdere duidelijk verschillende API-contexten op dezelfde host moet scheiden.
Gebruik meervoud als resource naam /url/meervoud-resource-naam
Gebruik meervoudige resource-namen in paden, omdat een resource-segment in REST doorgaans een collectie voorstelt.
/ondernemingen, /verenigingen/{id}/bestuurders/onderneming, /getOndernemingenEnkel singleton-resources, zonder collectie-karakter, kunnen in het enkelvoud staan (bv /profile-picture of /status)
Zorg voor correcte meervoudsvormen, vooral bij onregelmatige zelfstandige naamwoorden (bijv.
person→people, nietpersons).
Gebruik URL-friendly resource identifiers /url/url-friendly-identifiers
Resource identifiers in het pad moeten URL-safe, stabiel en voorspelbaar zijn.
Gebruik bij voorkeur identifiers met enkel onbetwiste URL-tekens (letters, cijfers, -, _, ., ~) en vermijd spaties of gereserveerde URL-tekens zoals /, ?, #.
Identifiers zijn bij voorkeur opaak: encodeer geen business-semantiek die doorheen de tijd kan veranderen.
Gebruik kebab-case voor pad segmenten /url/kebab-case-padsegmenten
Gebruik lowercase kebab-case voor alle padsegmenten.
/adressen-locaties, /milieu-attesten/adressenLocaties, /adressen_locaties, /AdressenLocatiesDit verhoogt leesbaarheid en consistentie over API's heen.
Gebruik lowerCamelCase voor path parameter namen /url/camelcase-pad-parameters
Path parameter namen (template variabelen) MOET lowerCamelCase gebruiken.
/ondernemingen/{ondernemingsNummer}/vestigingen/{vestigingsNummer}/social-secretariats/{socialSecretariatId}/ondernemingen/{ondernemings-nummer}, /ondernemingen/{ondernemings_nummer}Dit sluit aan bij de naamgeving van JSON properties en verbetert de consistentie bij code-generatie.
Overweeg het gebruik van (niet-)geneste URL's /url/geneste-urls
Gebruik geneste URL's wanneer een child-resource enkel betekenis heeft binnen de context van een parent-resource. Gebruik niet-geneste URL's voor resources met een eigen levenscyclus of wanneer je dezelfde resource ook buiten die parent-context wil opvragen.
Houd nesting beperkt (bij voorkeur maximaal 2 tot 3 niveaus) om URL-complexiteit te beperken.
Voorbeelden:
/ondernemingen/{ondernemingsNummer}/vestigingen/{vestigingsNummer}/vestigingen?ondernemingsNummer=...Geen file extensions in URL's /url/geen-file-extensions
Vermijd het gebruik van file extensions (zoals .json, .xml) in REST-URL's als betekenisvol onderdeel van de resource-identificatie.
Content negotiation via HTTP headers (bijv. Accept) is de aanbevolen manier om het gewenste responseformaat aan te geven, in plaats van verschillende URL's voor verschillende formaten.
In deze sectie lichten we een handvol (standaard) HTTP-headers toe, die we in bepaalde situaties het nuttigst vonden en die extra uitleg vereisen om ze effectief te gebruiken.
Doorgaans kun je de standaarddefinities voor HTTP request- en responseheaders gebruiken die door de richtlijn worden aangeboden, om de API te vereenvoudigen met algemeen herkenbare patronen. De best practice voor het importeren van headers met de hoogste leesbaarheid is als volgt:
paths:
/resource:
get:
parameters:
- $ref: '#/components/parameters/ETag'
components:
parameters:
ETag:
$ref: 'https://vdip.pages.vlaamseoverheid.ghe.com/specifications/rest/models/headers-1.0.0.yaml#/ETag'
responses:
Default:
headers:
ETag:
$ref: '#/components/parameters/ETag'
Gebruik standaard headers /headers/standaard-headers
API's mogen HTTP-headers gebruiken die gedefinieerd zijn door niet-verouderde RFC's (zie de lijst met standaard HTTP-headers).
Ondersteunde headers moeten expliciet worden gedocumenteerd in de API-specificatie.
Gebruik kebab-case met hoofdletters voor afzonderlijke woorden in HTTP-headers /headers/kebab-case-headers
Volg de naamgevingsconventie voor headers die door de meeste standaard headers wordt gebruikt (bijvoorbeeld in [RFC2616], [RFC4229], [RFC9110]).
Voorbeelden:
If-Modified-Since
Accept-Encoding
Content-ID
Language
Opmerking: HTTP-velden zijn niet hoofdlettergevoelig (zie [RFC9110] Section 5.1). Gebruik de bovenstaande conventie voor leesbaarheid en consistentie. Gangbare afkortingen zoals
IDzijn aanvaardbare uitzonderingen.
Gebruik Content-* headers correct /headers/content-headers
Content-* headers beschrijven de representatie in de message body en kunnen voorkomen in requests en responses.
Gebruik ze volgens hun HTTP-semantiek, inclusief:
Content-Disposition kan aangeven dat de representatie als bestand moet worden opgeslagen, en de voorgestelde bestandsnaam.Content-Encoding geeft compressie- of encryptiealgoritmen aan die op de content zijn toegepast.Content-Length geeft de lengte van de content aan (in bytes).Content-Language geeft aan dat de body bedoeld is voor mensen die een bepaalde menselijke taal/talen beheersen.Content-Location geeft aan waar de body anders gevonden kan worden (Location header moet in plaats daarvan worden gebruikt!).Content-Range wordt gebruikt in responses op range requests om aan te geven welk deel van de opgevraagde resource-representatie met de body wordt geleverd.Content-Type geeft het mediatype van de bodycontent aan.Gebruik Content-* headers niet als generieke metadata-dragers buiten hun door RFC gedefinieerde betekenis.
Overweeg ondersteuning voor de Idempotency-Key header /headers/idempotency-key
Bij het aanmaken of bijwerken van resources kan het nuttig of noodzakelijk zijn om sterk idempotent gedrag te garanderen, inclusief dezelfde responses, om dubbele uitvoering te voorkomen bij retries na time-outs en netwerkstoringen.
In het algemeen kan dit worden bereikt door een clientspecifieke unieke request key - die geen deel uitmaakt van de resource - via de Idempotency-Key header mee te sturen.
De unieke request key wordt tijdelijk opgeslagen, bijvoorbeeld gedurende 24 uur, samen met de response en (optioneel) de request-hash van het eerste request in een key-cache, ongeacht of dit succesvol was of faalde. De service kan nu de unieke request key opzoeken in de key-cache en de response uit de key-cache serveren, in plaats van het request opnieuw uit te voeren, om idempotent gedrag te waarborgen. Optioneel kan de service de request-hash op consistentie controleren voordat de response wordt geserveerd. Als de key niet in de key-store staat, wordt het request zoals gebruikelijk uitgevoerd en wordt de response opgeslagen in de key-cache.
Dit maakt het mogelijk voor clients om requests veilig te herhalen na time-outs, netwerkstoringen, enz., terwijl ze meerdere keren dezelfde response ontvangen.
Opmerking: De request retry in deze context vereist dat exact hetzelfde request wordt verstuurd, d.w.z. wijzigingen aan het request die het resultaat veranderen zijn niet toegestaan. De request-hash in de key-cache kan bescherming bieden tegen dit misbruik. Het wordt aanbevolen dat de service een dergelijk request afwijst met statuscode 400.
Belangrijk: Om betrouwbare idempotente uitvoeringssemantiek te garanderen, moeten de resource en de key-cache met harde transactiesemantiek worden bijgewerkt - rekening houdend met alle mogelijke valkuilen van fouten, time-outs en gelijktijdige requests in een gedistribueerd systeem. Dit maakt een correcte implementatie, die de lokale context overstijgt, zeer moeilijk.
De Idempotency-Key header moet als volgt worden gedefinieerd, maar je bent vrij om je eigen vervaltijd te kiezen:
components:
headers:
Idempotency-Key:
$ref: 'https://vdip.pages.vlaamseoverheid.ghe.com/specifications/rest/models/headers-1.0.0.yaml#/Idempotency-Key'
Zorg ervoor dat je de vervaltijd van de idempotency key documenteert
De X-Correlation-ID (CorrelationId) en X-Request-ID (RequestId) maken het mogelijk om een set van berichten gekoppeld aan een transactie of een uniek bericht binnen een transactie te identificeren.
Het onderstaande schema toont hoe deze 2 waarden worden gebruikt:
Door beide waarden te gebruiken, kunnen specifieke berichten worden getraceerd. In het geval van fouten of vragen kan:
de volledige transactie worden gevolgd op basis van de CorrelationId
informatie voor een specifiek request worden geïsoleerd op basis van de RequestId
CorrelationId toevoegen aan de request /headers/correlation-id
Een CorrelationId groepeert 1 of meer berichten in een transactie, waardoor berichten doorheen meerdere systemen kunnen worden getraceerd.
In de request-header wordt een X-Correlation-ID meegestuurd, in het formaat van een UUIDv4 (bv. a6d87d0e-2454-4501-8110-ecc082aa975f).
De waarde in de X-Correlation-ID-header in de response die wordt teruggestuurd, moet gelijk zijn aan de waarde in de request.
RequestId toevoegen aan de request /headers/request-id
Een RequestId identificeert elk request op een unieke manier, waardoor exacte berichten binnen transacties nauwkeurig kunnen worden aangewezen, bijvoorbeeld voor support.
In de request-header wordt een X-Request-ID meegestuurd, in het formaat van een UUIDv4 (bv. 0d1e63a3-b635-4d50-ba7f-34b7176defdf).
De waarde in de X-Request-ID-header in de response die wordt teruggestuurd, moet gelijk zijn aan de waarde in de request (als deze aanwezig is).
Als er geen X-Request-ID in de request aanwezig is, dan moet de service een eigen X-Request-ID genereren en terugsturen in de response.
Gebruik de correcte HTTP methoden /request/http-methoden
HTTP methoden MOETEN gebruikt worden volgens hun standaard semantiek:
| Method | Safe | Idempotent | Request body | Response body | Primair gebruik |
|---|---|---|---|---|---|
GET |
Ja | Ja | Nee | Ja | Ophalen van een resource |
POST |
Nee | Nee | Meestal | Meestal | Aanmaken of verwerken |
PUT |
Nee | Ja | Ja | Optioneel | Volledige vervanging |
PATCH |
Nee | Nee | Ja | Optioneel | Gedeeltelijke update |
DELETE |
Nee | Ja | Nee | Optioneel | Verwijderen |
HEAD |
Ja | Ja | Nee | Nee | Bestaan van metadata controleren |
OPTIONS |
Ja | Ja | Nee | Ja | Beschikbare methoden opvragen |
GET: leesoperatie zonder state change.POST: aanmaken van een nieuwe resource of een command-achtige actie. Bij aanmaken geeft de server 201 Created terug met de URL van de nieuwe resource in de Location-header.PUT: volledige vervanging van een bestaande resource. De client levert alle velden aan; ontbrekende optionele velden vallen terug op de standaardwaarden.PATCH: partiële update via JSON Merge Patch ([RFC7396]). Velden met null worden verwijderd; afwezige velden blijven ongewijzigd.DELETE: verwijderen van een resource.HEAD: identiek aan GET, maar zonder response body. Nuttig om het bestaan van metadata van een resource te controleren.OPTIONS: geeft de toegelaten methoden voor een resource terug via de Allow-header.Gebruik geen GET voor operaties met side-effects en vermijd tunneling van methoden via query parameters.
Gebruik lowerCamelCase voor query parameters /url/camelcase-query-params
lowerCamelCase MOET gebruikt worden voor alle query parameters.
?fieldName=foo, ?pageSize=123?field-name=foo, ?field_name=foo, ?FieldName=fooDit sluit aan bij de naamgeving van JSON properties en verhoogt consistentie voor API-consumers.
Herhalende query parameters /request/herhalende-params
Array-achtige queryparameters MOETEN in de herhalende (exploded) vorm worden opgegeven, conform [RFC6570] sectie 3.2.8.
Gebruik:
?status=actief&status=gepauzeerd?id=123&id=456&id=789Definieer dit expliciet in OpenAPI met style: form en explode: true.
Blijf bij de standaard geaccepteerde query parameters /url/standaard-query-params
Gebruik waar mogelijk de gangbare query-parameternamen met hun conventionele betekenis:
q: vrije zoekquery (filtering op tekst)sort: sorteervolgorde (bijv. naam,-aangemaaktOp)fields: projection/selectie van responseveldenembed: inline opnemen van gerelateerde resourcesoffset en limit: offset-based paginatieIntroduceer geen nieuwe parameternaam als een standaardparameter hetzelfde doel dekt.
Gebruik officiële HTTP-statuscodes /request/officiele-statuscodes
Je mag uitsluitend officiële HTTP-statuscodes gebruiken, en dat consistent met hun bedoelde semantiek. Officiële HTTP-statuscodes zijn gedefinieerd via RFC-standaarden en geregistreerd in de IANA Status Code Registry. De belangrijkste RFC-standaarden zijn [RFC9110] HTTP Semantics, sectie 15: Status Codes en [RFC6585] HTTP: Additional Status Codes.
Gebruik alleen de meest voorkomende HTTP-statuscodes /request/meest-voorkomende-codes
De meest gebruikte codes worden het best begrepen; vermijd minder vaak gebruikte codes die gemakkelijk misverstanden veroorzaken door minder vertrouwde semantiek en API-specifieke interpretaties.
Belangrijk: zolang je gebruik van HTTP-statuscodes goed gedekt is door de hier gedefinieerde semantiek, hoef je dit niet te beschrijven, om overbelasting met vanzelfsprekende informatie en het risico op inconsistente definities te vermijden. Alleen als de HTTP-statuscode niet in de onderstaande lijst staat, of als het gebruik ervan extra informatie vereist naast de goed gedefinieerde semantiek, moet de API-specificatie een duidelijke beschrijving van de HTTP-statuscode in de response geven.
Bij twijfel over het correcte gebruik van een HTTP-statuscode, raadpleeg [RFC9110].
Gebruik de meest specifieke HTTP-statuscodes /request/meest-specifieke-codes
De meest specifieke HTTP-statuscode MOET gebruikt worden wanneer je informatie teruggeeft over de verwerkingsstatus van een verzoek of over foutsituaties.
Gebruik code 429 met Retry-After header voor rate limiting /request/rate-limit
API's die de request rate van clients willen beheren, MOETEN responsecode 429 (Too Many Requests) gebruiken als de client de request rate heeft overschreden (zie [RFC6585]).
De response MOET een Retry-After header bevatten met ofwel een vertraging in seconden (delta-seconds), ofwel een HTTP-date waarop de client opnieuw mag proberen (zie [RFC9110] sectie 10.2.3).
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/problem+json
Communiceer rate limit quota via RateLimit-Policy en RateLimit headers /request/rate-limit-headers
API's die rate limiting toepassen, KUNNEN de in draft-ietf-httpapi-ratelimit-headers voorgestelde RateLimit-Policy en RateLimit headers gebruiken.
HTTP/1.1 200 OK
RateLimit-Policy: "default";q=100;w=60
RateLimit: "default";r=75;t=45
Interpretatie: de client mag 100 requests per 60 seconden; er resten nog 75 requests in de komende 45 seconden.
Bij complexe rate limiting op meerdere niveaus (bv. API-breed, per client en per IP) kunnen alle policies in dezelfde headers worden gecommuniceerd:
HTTP/1.1 200 OK
RateLimit-Policy: "api";q=60;w=1, "client";q=30;w=1;pk=:Y2xpZW50LTQy:, "ip";q=30;w=1;pk=:MTAuMC4wLjE=:
RateLimit: "api";r=58;t=1, "client";r=28;t=1;pk=:Y2xpZW50LTQy:, "ip";r=30;t=1;pk=:MTAuMC4wLjE=:
HTTP/1.1 429 Too Many Requests
Retry-After: 2
RateLimit-Policy: "client";q=30;w=1;pk=:Y2xpZW50LTQy:
RateLimit: "client";r=0;t=2;pk=:Y2xpZW50LTQy:
Content-Type: application/problem+json
Onderstaande tabel geeft de meest voorkomende combinaties van HTTP-statuscodes per methode. Een X geeft aan dat de code van toepassing kan zijn; een - betekent dat de combinatie bij voorkeur niet gebruikt wordt.
| Code | GET | HEAD | POST | PUT | PATCH | DELETE | OPTIONS |
|---|---|---|---|---|---|---|---|
| 200 OK | X | X | X | X | X | X | X |
| 201 Created | - | - | X | X | - | - | - |
| 202 Accepted | - | - | X | - | - | - | - |
| 204 No Content | - | - | - | X | X | X | - |
| 301 Moved Permanently | X | X | - | X | X | X | X |
| 303 See Other | X | X | X | X | X | X | X |
| 304 Not Modified | X | X | - | - | - | - | - |
| 307 Temporary Redirect | X | X | X | X | X | X | X |
| 400 Bad Request | X | X | X | X | X | X | X |
| 401 Unauthorized | X | X | X | X | X | X | X |
| 403 Forbidden | X | X | X | X | X | X | X |
| 404 Not Found | X | X | X | X | X | X | X |
| 405 Method Not Allowed | X | X | X | X | X | X | - |
| 406 Not Acceptable | X | X | X | X | X | X | X |
| 409 Conflict | - | - | X | X | X | X | - |
| 412 Precondition Failed | - | - | X | X | X | X | - |
| 413 Payload Too Large | - | - | X | X | X | - | - |
| 415 Unsupported Media Type | X | X | X | X | X | X | X |
| 429 Too Many Requests | X | X | X | X | X | X | X |
| 500 Internal Server Error | X | X | X | X | X | X | X |
| 502 Bad Gateway | X | X | X | X | X | X | X |
| 503 Service Unavailable | X | X | X | X | X | X | X |
De actie is succesvol ontvangen, begrepen en verwerkt.
| Code | Beschrijving | Methoden |
|---|---|---|
| 200 OK | Standaard succescode wanneer de aanvraag succesvol is verwerkt en er een response body wordt teruggegeven. | GET, HEAD, PUT, POST, PATCH, DELETE, OPTIONS |
| 201 Created | Een nieuwe resource is succesvol aangemaakt. De response bevat bij voorkeur de Location-header met de URI van de nieuwe resource. |
POST, PUT (alleen bij creatie) |
| 202 Accepted | De aanvraag is geaccepteerd voor asynchrone verwerking. Wordt typisch gebruikt voor langlopende taken. | POST |
| 204 No Content | De aanvraag is succesvol verwerkt maar er is bewust geen response body. | PUT, PATCH, DELETE |
Verdere actie is vereist om de aanvraag te voltooien.
| Code | Beschrijving | Methoden |
|---|---|---|
| 301 Moved Permanently | De resource is permanent verplaatst naar een nieuwe URI. De nieuwe URI staat in de Location-header. Gebruik geen 301 bij POST-requests: sommige clients zetten een POST na een 301 om naar een GET ([RFC9110] §15.4.2). |
Alle behalve POST |
| 303 See Other | Verwijst de client naar een andere URI via een GET-request. Bruikbaar na langlopende acties. | Alle |
| 304 Not Modified | Bij conditional requests ([RFC9110] §13): de resource is niet gewijzigd sinds het laatste verzoek. Bespaart bandbreedte. | GET, HEAD |
| 307 Temporary Redirect | Tijdelijke doorverwijzing naar een andere URI. De client MOET de oorspronkelijke methode behouden. | Alle |
De aanvraag bevat een fout aan clientzijde.
Voor foutcodes (4xx en 5xx) MOET de response body het Problem JSON-formaat gebruiken conform [RFC9457]. Zie de sectie REST Foutenafhandeling voor gestandaardiseerde fouttypes en voorbeelden.
| Code | Beschrijving | Methoden |
|---|---|---|
| 400 Bad Request | De aanvraag is ongeldig (syntactisch of semantisch). Generieke clientfout wanneer geen specifiekere 4xx-code van toepassing is. | Alle |
| 401 Unauthorized | Authenticatie is vereist of het meegegeven token is ongeldig. | Alle |
| 403 Forbidden | De client is geauthenticeerd maar heeft onvoldoende rechten om de gevraagde actie uit te voeren. | Alle |
| 404 Not Found | De gevraagde resource bestaat niet. Geef bij collecties een lege lijst (200) terug in plaats van een 404. | Alle |
| 405 Method Not Allowed | De gebruikte HTTP-methode wordt niet ondersteund voor deze resource. De response MOET een Allow-header bevatten met toegestane methoden. |
Alle behalve OPTIONS |
| 406 Not Acceptable | Het gevraagde mediatype (via Accept-header) kan niet geleverd worden. |
Alle |
| 409 Conflict | De aanvraag is in conflict met de huidige state van de resource. Bijvoorbeeld bij concurrerende updates of het verwijderen van een niet-lege collectie. | POST, PUT, PATCH, DELETE |
| 412 Precondition Failed | Een conditionele header (If-Match, If-Unmodified-Since) is niet voldaan. Alleen te gebruiken voor HTTP-condities, niet voor businessvalidatie. |
POST, PUT, PATCH, DELETE |
| 413 Payload Too Large | De request body is groter dan de server accepteert. | POST, PUT, PATCH |
| 415 Unsupported Media Type | Het mediatype van de request body (via Content-Type) wordt niet ondersteund. |
Alle |
| 429 Too Many Requests | De client heeft de toegestane request rate overschreden. De response bevat bij voorkeur een Retry-After-header. |
Alle |
De server kon een geldige aanvraag niet verwerken.
| Code | Beschrijving | Methoden |
|---|---|---|
| 500 Internal Server Error | Generieke serverfout bij onverwachte problemen. De client mag dezelfde aanvraag opnieuw proberen. | Alle |
| 502 Bad Gateway | De server heeft als gateway of proxy een ongeldige response ontvangen van een upstream-service. | Alle |
| 503 Service Unavailable | De service is tijdelijk onbeschikbaar (overbelasting of gepland onderhoud). De response bevat bij voorkeur een Retry-After-header. |
Alle |
Bij fouten moet de API een correcte HTTP-responscode teruggeven, samen met een payload die voldoet aan [RFC9457], en die het probleem beschrijft.
Zorg voor duidelijke en informatieve foutmeldingen. Zo kan Digitaal Vlaanderen ook de afnemers duidelijk informeren.
Voorbeeld van de structuur voor een foutboodschap:
De
error-idin deinstance-waarde kan in de meeste gevallen deX-Correlation-Idzijn. De uiteindelijkeinstance-waarde wordt dan bijvoorbeeldurn:be.vlaanderen.vdip:onderneming:5cd3f329-fe33-4705-8115-e22638eb0f4f. Een supportmedewerker kan hieruit snel afleiden dat het over deOndernemingdienst gaat bijVDIPmet referentie5cd3f329-fe33-4705-8115-e22638eb0f4f.
Ondersteun Problem JSON voor foutresponses /error/problem-json
Voor foutresponses MOET het standaardformaat application/problem+json, conform [RFC9457] gebruikt worden.
Voorzie dit formaat voor zowel clientfouten (4xx) als serverfouten (5xx), zodat clients consistente en machineleesbare foutinformatie krijgen.
Gebruik minimaal deze velden in de response:
type: stabiele identifier van het probleemtype (bv. https://data.vlaanderen.be/id/Uitzondering/onderneming/40001)title: korte, menselijk leesbare samenvattingdetail: concrete foutuitleg voor deze specifieke situatieinstance: identifier van de specifieke foutinstantie (optioneel maar aanbevolen)Foutresponses MOETEN expliciet gedocumenteerd worden in OpenAPI met application/problem+json als content-type.
Gebruik hiervoor het standaard Problem-schema: https://vdip.pages.vlaamseoverheid.ghe.com/specifications/rest/models/problem-1.0.0.yaml#/Problem
NOTE: Clients moeten robuust blijven: infrastructuurcomponenten of uitzonderlijke foutpaden kunnen in sommige gevallen toch geen Problem JSON teruggeven.
NOTE: Clients MOGEN NIET het
titleofdetailvelden parsen voor logica op toe te passen, andere properties zijn beter geschikt voor machineverwerking.
Geen stacktraces blootstellen /error/geen-stacktraces
In productieomgevingen mogen er geen stacktraces worden blootgesteld in foutresponses.
Stacktraces bevatten implementatiedetails die geen deel uitmaken van een API en waarop clients nooit mogen vertrouwen. Bovendien kunnen stacktraces gevoelige informatie lekken die partners en derden niet mogen ontvangen, en kunnen ze aanvallers inzicht geven in mogelijke kwetsbaarheden.
Context De aanvraag heeft ongeldige parameters en/of de validatie van de aanvraag is gefaald. Validatie-errors zijn het gevolg van een businessevaluatie van de payload meegegeven in een voorafgaande API-interactie. Validatie-errors kunnen het verzetten van interactie met (onderdelen van) de API verhinderen.
Validatie-errors worden meegegeven als een lijst, met de naam errors. De elementen van die lijst volgen de basisstructuur van de standaarderrors: type, title en detail zijn verplicht in dit geval. Eigen uitbreidingen zijn toegestaan.
De client moet de request niet herhalen als er geen wijzigingen zijn.
Referentie https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400
Context
De gebruiker/client is correct geauthenticeerd maar heeft geen toegang tot de resource.
Als het token ongeldig is - bijv. omdat het vervallen is - moet een
401 Unauthorized-fout worden teruggegeven.
Referentie https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403
Context
De resource bestaat niet (voor deze gebruiker). Afhankelijk van de businessrules kan een 404-fout teruggeven worden als er geen data beschikbaar is voor een gebruiker.
Geef een lege collectie terug ipv een 404-fout bij het opvragen van collecties. Bij het ophalen van een specifiek - niet bestaand - item kan een 404-fout wel een geldig antwoord zijn.
Referentie https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
Context
Foutcode bij onverwachte fouten in de service die niet worden opgevangen door andere foutcodes.
Als er bij runtime exceptions geen betere fout past, kan deze foutcode gebruikt worden als een ‘last resort’.
Referentie https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500
Standaard verwachten we een Bearer-token in de Authorization header volgens de [RFC6750] specificatie.
De structuur van de header: Authorization: Bearer <token>
Beveilig endpoints /security/beveilig-endpoints
Alle REST API endpoints MOETEN beveiligd zijn, hiervoor MOET OAuth 2.0 gebruikt worden. De API specificatie MOET de vereiste OAuth scopes duidelijk vermelden OpenAPI specificatie (zie /docs/api-metadata regel).
Definieer en wijs permissies (scopes) toe /security/definieer-scopes
Ieder endpoint van een API MOET beveiligd zijn met de correcte permissies. Voor de namen van de permissies (scopes) wordt er sterk verwacht dat deze de conventie volgen zoals bepaald in deze guide. (bestaande APIs hoeven niet te worden gewijzigd)
De API specificatie MOET de vereiste OAuth scopes duidelijk en volledig vermelden onder #/paths/{path}/{operation}/security/{scheme}/scopes
Volg de naam conventie voor permissies (scopes) /security/scope-naam-conventie
Iedere permissie (scope) die binnen ACM OAuth wordt toegewezen MOET de volgende conventie te volgen. Permissie namen zijn steeds in kleine letters, zonder spaties, en worden gescheiden door underscores.
Conventie:
dv_vdip_resource[_subresource][_toegangsniveau]
Minimaal verplicht:
dv_vdip_ is de prefix die aangeeft dat deze permissie behoort tot het Digitaal Vlaanderen VDIP platform.resource de naam is van de API, bv milieu, onderneming, organisatieOptioneel:
subresource is de optionele operatie (resource) die aangesproken wordt, dit kan gebruikt worden om meer specifieke resources af te schermen in het bijzonder wanneer er schrijf operaties toegelaten worden. Er wordt maximaal 1 subniveau toegelaten.toegangsniveau is het deel dat definieert welke toegang van toepassing is, afhankelijk van welk authorisatiemodel je gebruikt kan dit aanwezig zijn. bv:create staat voor Create (POST)read staat voor Read (GET)update staat voor Update (PUT/PATCH)delete staat voor Delete (DELETE)admin staat voor Admin (alle rechten)user staat voor standaard gebruiker (beperkte rechten)editor staat voor gebruiker met extra schrijfrechtenCRUD
Role-based
Gebruik Authorization header /security/authorization-header
De Authorization-header wordt gebruikt om API’s te beveiligen, de API-services MOETEN de standaard Bearer token gebruiken zoals gespecificeerd in [RFC6750].
Er worden geen authorisatiegegevens verstuurd via een query parameter: URLs kunnen gecachet worden in de browser en/of gelogd worden. Op deze manier kunnen credentials lekken.
Voorbeeld:
Authorization: Bearer XyZAbCd1234
Enkel ACM OAuth tokens worden geaccepteerd /security/acm-oauth-tokens
Enkel ACM OAuth tokens worden geaccepteerd voor authenticatie en autorisatie van API-aanroepen.
Andere vormen van authenticatie, zoals Basic Authentication of API keys, worden niet geaccepteerd.
Opmerking: In uitzonderlijke gevallen kan het nodig zijn dat OAuth tokens van andere IdPs worden geaccepteerd (bv BOSA of eHealth). "Comply-or-Explain:" met uitgebreide motivatie en gedegen security review is vereist in deze gevallen, gezien dit een afwijking is in de veiligheidsketting binnen Digitaal Vlaanderen is.
Datum formaat in ISO8601 /data-format/datum-iso8601
Tijdstippen die deel uitmaken van een respons MOETEN in ISO8601 formaat en genormaliseerd worden teruggegeven als UTC met tijdzone-informatie.
We accepteren en geven enkel tijden in UTC terug ('Z' als tijdzone-indicatie), uit ervaring hebben we geleerd dat tijdzone-indicaties vaak verkeerd geïnterpreteerd worden (bv DST), wat tot verwarring en fouten kan leiden. Eventuele verdere tijdzone conversies horen client-side te gebeuren, wij geven enkel tijden terug in UTC, en dat is ook de enige tijdzone-indicatie die we accepteren.
De volgende zijn correct:
2016-01-252016-01-25T21:34:55Z zonder subsecondenaanduiding2016-01-25T21:34:55.451Z met subsecondenaanduiding, we ondersteunen enkel 3 cijfers na de secondeFormaten zonder tijdszone-indicatie worden NIET geaccepteerd, bv:
2016-01-25T21:34:55
UITZONDERING: datum-tijd formaten in headers die reeds in andere standaarden gedefinieerd zijn, bv
Dateheader in HTTP, mogen het formaat volgen dat in die standaard gedefinieerd is, bvSun, 06 Nov 1994 08:49:37 GMTvolgens [RFC7231].
Landcode in [ISO3166-1] alpha-3 /data-format/landcode-iso3166
Landcodes die deel uitmaken van een respons MOETEN genormaliseerd teruggegeven worden in ISO3166-1 alpha-3 formaat, bv BEL voor België, NLD voor Nederland, DEU voor Duitsland.
Het gebruik van de alpha-3 codes aligneert met wat Europa voorstelt.
Taalcode in [ISO-639-1-2002] /data-format/taalcode-iso639
Taalcodes die deel uitmaken van een respons MOETEN genormaliseerd teruggegeven worden in ISO639-1 formaat, bv nl voor Nederlands, fr voor Frans, de voor Duits.
Valuta in [ISO4217] /data-format/valuta-iso4217
Valutacodes die deel uitmaken van een respons MOETEN genormaliseerd teruggegeven worden in ISO4217 formaat, bv EUR voor Euro, USD voor US Dollar, JPY voor Japanse Yen.
Binaire data wordt geëncodeerd in base64url /data-format/binaire-base64url
Binaire data die deel uitmaakt van een respons MOET geëncodeerd worden in base64url formaat, zoals gedefinieerd in [RFC4648].
Binnen de JSON payload wordt dit weergegeven als een string property van het binary formaat, tenzij er een betere semantische datatype beschikbaar is, bv file of image.
JSON als payload /json/json-als-payload
REST APIs gebruiken JSON als payload formaat voor request en response body.
In sommige gevallen kan hier van afgeweken worden voor specifieke use-cases (comply-or-explain), bv bulk upload in CSV.
Design 1 resource voor lezen en schrijven /json/resource-lezen-schrijven
Gebruik bij voorkeur één logisch resourceschema voor zowel read als write, in plaats van aparte modellen zonder noodzaak.
Gebruik OpenAPI-attributen om verschillen expliciet te maken:
writeOnly wanneer ze enkel in requests gebruikt worden (bijv. credentials)readOnly wanneer ze enkel in responses voorkomen (bijv. identifiers, timestamps, server-calculated fields)Zo blijft de API consistenter voor clients en beperk je modelduplicatie.
Gebruik standaard media-types /json/standaard-media-types
Gebruik geregistreerde standaard media-types in Content-Type en Accept.
Voor JSON APIs is application/json de standaard; voor foutresponses gebruik je bij voorkeur application/problem+json ([RFC9457]).
Vermijd custom media-types tenzij er een duidelijke, gedocumenteerde noodzaak is (comply-or-explain).
Non-JSON media types gebruiken specifieke (standaard) formaten /json/non-json-media-types
Wanneer JSON niet geschikt is, gebruik dan een specifiek standaard media type dat overeenkomt met het payload-formaat, bijvoorbeeld:
text/csv voor CSV-exportapplication/pdf voor PDF-documentenapplication/octet-stream voor binaire downloadsmultipart/form-data voor uploads met bestandenDocumenteer per operatie expliciet welke request- en response-media-types ondersteund worden.
Retourneer altijd een JSON object als top-level data structuur /json/top-level-object
Er MOET altijd een JSON object {...} als top-level datastructuur in de responses gebruikt worden.
Retourneer geen top-level arrays of primitieve types.
Gebruik een enveloppe-object met semantische velden, bijvoorbeeld:
data of items voor de payloadcount, offset, limit voor paginatiemetadatalinks voor navigatie/hypermediaGebruik lowerCamelCase voor JSON property namen /json/camelcase-property-names
JSON property namen in request- en response-body's MOETEN lowerCamelCase gebruiken.
ondernemingsNummer, maatschappelijkeNaam, aangemaaktOpondernemings_nummer, ondernemings-nummer, OndernemingsNummerDit is de gangbare conventie in JSON/JavaScript-ecosystemen en bevordert compatibiliteit met code-generatietools.
Collecties en Paginering wordt eerst verder besproken in de Github Discussie: https://vlaamseoverheid.ghe.com/DV-Data-Platform/vdip/discussions/2
Voorbeeld van een API die voldoet aan de richtlijnen in deze specificatie vind je terug hier: onderneming-v1.2.3.yaml