Document toolboxDocument toolbox

Documentatie voor klanten en partners van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers

Algemene REST API-specificaties

Owned by dimitry.declercq (Unlicensed)
Last updated: 27 Feb, 2024 by Heidi Vannevel
11 min read

Over deze documentatie

In deze documentatie vindt u de algemene richtlijnen om REST API’s te bouwen die data aanleveren aan Mijn Burgerprofiel. Dit document bouwt verder op de bestaande richtlijnen van de Expertise Groep Architectuur: https://data.vlaanderen.be/doc/richtlijnen/iv-rest-api-richtlijnen/

Gerelateerde standaarden en richtlijnen

In deze documentatie wordt er verder gebouwd op de volgende standaarden en richtlijnen van de Vlaamse Overheid:

Het is sterk aanbevolen om deze standaarden en richtlijnen te kennen vóór verder te gaan met dit document.

REST URL-vormrichtlijnen

Hiervoor worden de richtlijnen van de Expertise Groep Architectuur gevolgd.

  • Volg zeker de richtlijn m.b.t. het versioneren van de API's. Voeg een versienummer toe in de URL en gebruik hiervoor enkel natuurlijke getallen, bv v1, v2, …

  • Vermijd breaking changes binnen een versie. Zodra er breaking changes bestaan, moet er een volgende versie gereleased te worden.

  • Concreet ziet de basisstructuur van een URL er als volgt uit: https://{hostname}/{version}/{resource}/{identifier}.

  • Een voorbeeld van een URL met parameters: https://mbp.vlaanderen.be/v3/attesten/ac518dbc?taal=nl&nisCode=31005

API-designrichtlijnen

Hiervoor worden de richtlijnen van de Expertise Groep Architectuur gevolgd, met aandacht voor de volgende punten, waaraan er in dit document nog extra invulling gegeven wordt.

Onderwerp

Regel

Onderwerp

Regel

Datum & tijd

  • De datum- en tijdsnotatie volgen het ISO8601-formaat.

  • Tijdstippen die deel uitmaken van een respons worden genormaliseerd teruggegeven als UTC met tijdzone-informatie.

De volgende zijn correct:

  • Datum: 2016-01-25

  • Datum & tijd met tijdzone indicatie:

    • 2016-01-25T21:34:55.451+00:00 of 2016-01-25T21:34:55.451Z

      • subsecondenaanduiding kan in 3 cijfers na de seconde, 6 cijfers na de seconde of 9 cijfers na de seconde

      • tot op de seconde kan ook: 2016-01-25T21:34:55Z

Formaten zonder tijdszone-indicatie worden NIET geaccepteerd, bv: 2016-01-25T21:34:55

Payload

  • Het standaardformaat voor een respons is JSON. De structuur van deze JSON dient te voldoen aan RMM niveau 3 .

  • Indien een object niet beschikbaar is en verplicht terug te geven is volgens het domein, heeft het de waarde null.

  • Indien een lijst van objecten niet beschikbaar is en verplicht terug te geven is volgens het domein, wordt een lege lijst verwacht.

  • Gebruik bij voorkeur camelCase voor attributtnamen.

HTTP-statuscodes

Maak overwogen gebruik van HTTP Statuscodes en beperk waar mogelijk tot een subset.

Zie de Expertise Groep Architectuur richtlijnen en RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 voor meer informatie.

Standaarderrorpayload

Standaarderrors zijn het gevolg van technische, systeem- of softwareproblemen. Deze worden weergegeven met de overeenkomstige HTTP errorcode en een standaard error payload.

Validatie-error payload

Validatie-errors zijn het gevolg van een businessevaluatie van de payload meegegeven in voorafgaande API-interactie. Validatie-errors verhinderen mogelijks het verzetten van interactie met (onderdelen van) de API.

Er bestaat geen vaste correlatie tussen HTTP-errorcodes en het bestaan van validatie-errors. Het kan dus best voorkomen dat een HTTP-responscode 200 wordt ontvangen met validatie-errors. Bijvoorbeeld wanneer een draftobject wordt opgeslagen en al de validatie-errors hierbij worden teruggegeven. Het is aan de designer van de REST API om zo goed mogelijk de HTTP-responscode te laten overeenkomen met het bestaan van validatie-errors en hiermee de interactie van de API te sturen.

Validatie-errors worden meegegeven als een lijst met als 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.

HTTP Header

Bebruik de standaard HTTP-headers - waar mogelijk - om het gebruik van de API te bevorderen.

CorrelatieID

Om de verwerking van een API request te kunnen volgen is het zinvol om een correlatieID te initiëren door de proxy verbonden met de externe wereld. Deze correlatieID moet worden doorgegeven door elke verwerkende service naar zijn achterliggende API-oproepen. Op deze manier kan de verwerking van 1 externe request over verschillende API's heen gevolgd worden. Deze correlatieID zal worden opgeslagen in een HTTP header x-correlation-id.

Collecties

Bij het opvragen van collecties wordt verwacht dat er paginering ondersteund wordt, ten minste op niveau van de API-structuur.

Paginering

In de URL worden er 2 query parameters ondersteund

  • limit: Aantal resultaten op 1 resultatenpagina (1-based)

  • offset: Volgnummer van het eerstvolgend resultaat dat als eerste wordt verwacht (startend bij 0).

Voorbeeld van 10 resultaten per pagina opvragen waarbij de eerste pagina wordt opgevraagd: https://mbp.vlaanderen.be/v3/attesten?limit=10&offset=0

Voorbeeld van de tweede pagina die resultaten teruggeeft beginnend bij het 11de resultaat: https://mbp.vlaanderen.be/v3/attesten?limit=10&offset=10

Metadata

Bij gepagineerde data is het verplicht op metadata mee te sturen over de paginering. Doe dit door een pagemetadata-element toe te voegen aan het responselement:

"pageMetadata": { "offset": 0, "size": 10, "totalItems": 50, }

  • offset (verplicht) start van de offset op de teruggegeven pagina

  • size (verplicht) het aantal objecten teruggegeven op deze pagina

  • totalItems (verplicht, indien gekend) het totaal aantal objecten in de gehele collectie - als het totaal aantal items niet gekend is, moet deze parameter niet teruggegeven worden

Links

Bij het teruggeven van een collectie moeten er ook bepaalde links aanwezig zijn. De volgende zijn verplicht bij het teruggeven van een collectie:

  • self de opgegeven href wijst naar de huidige pagina van de collectie.

  • next (alleen als er een volgende pagina is) de opgegeven href wijst naar de volgende pagina van de collectie, alleen als er effectief een volgende pagina is

  • prev (enkel er een vorige pagina is) de opgegeven href wijst naar de vorige pagina van de collectie, alleen als er effectief een vorige pagina is.

  • first de opgegeven href wijst naar de eerste pagina van de collectie.

  • last de opgegeven href wijst naar de laatste pagina van de collectie.

Headers

Authorization

De Authorization-header wordt gebruikt om API’s te beveiligen, de API-services gebruiken standaard een Bearer token.

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

CorrelationId en RequestId

De CorrelationId en RequestId maken het mogelijk om een set van berichten gelinkt aan een transactie of een uniek bericht binnen een transactie te identificeren.

Het onderstaande schema toont hoe deze 2 waarden gebruikt worden:

Door de beide waarden te gebruiken, kunnen specifieke berichten getraceerd worden. In het geval van fouten of vragen kan:

  • de hele transactie gevolgd worden, op basis van de CorrelationId

  • informatie voor een specifiek request geïsoleerd worden, op basis van de RequestId

CorrelationId

Optioneel, groepeert 1 or meer berichten in een transactie waardoor berichten traceren doorheen meerdere systemen kan.

  • Er wordt in de header van de request een X-Correlation-ID meegestuurd, in het formaat van een UUIDv4 (bv a6d87d0e-2454-4501-8110-ecc082aa975f)

  • De waarde in de respons van de X-Correlation-ID-header die teruggestuurd wordt, moet gelijk zijn aan de waarde in de request (als deze aanwezig is).

RequestId

Optioneel, identificeert elk request op een unieke manier waardoor exacte berichten binnen transacties nauwkeurig aanwijzen kan, zoals bijv. voor support.

  • Er wordt in de header van de request een X-Request-ID meegestuurd, in het formaat van een UUIDv4 (bv 0d1e63a3-b635-4d50-ba7f-34b7176defdf).

  • De waarde in de respons van de X-Request-ID -header die teruggestuurd wordt, moet gelijk zijn aan de waarde in de request (als deze aanwezig is).

Voorbeeld

X-Correlation-ID: 5cd3f329-fe33-4705-8115-e22638eb0f4f X-Request-ID: 0b2506d4-14d4-446b-a7a9-3a2944b5efe9

Standaard foutberichten

De foutberichten die teruggeven worden, moeten conform API-design richtlijnen zijn. Deze zijn gebaseerd op RFC 7807 - Problem Details for HTTP API's.

Over foutberichten

Bij fouten moet de API een correcte HTTP-responscode teruggeven, samen met een payload die voldoet aan RFC 7807, en die het probleem beschrijft.

Over responscodes

Beperkt de responscodes tot de meest courante, in lijn met de richtlijnen van de Expertise Groep Architectuur:

  • 400 Bad Request De aanvraag heeft invalide parameters en/of de validatie van de aanvraag is gefaald

  • 401 Unauthorized Het authenticatietoken van de gebruiker is verlopen

  • 403 Forbidden De gebruiker heeft geen toegang tot de resource

  • 404 Not Found De specifieke resource is niet gevonden

  • 500 Internal Server Error Voor onverwachte fouten in de service die niet opgevangen worden door een andere foutcode

Voorbeeld van de structuur voor een foutboodschap:

HTTP/1.1 404 Not Found Content-Type: application/problem+json X-Correlation-Id: "5cd3f329-fe33-4705-8115-e22638eb0f4f" X-Request-Id: "0b2506d4-14d4-446b-a7a9-3a2944b5efe9" { "status": <zelfde als http code>, "type": "https://foo.vlaanderen.be/errors/<type>" "title": "<korte titel>", "detail": "<korte omschrijving van de fout>", "instance": "urn:be.vlaanderen.foo:bar:<error-instance-id>" }

De Expertise Groep Architectuur verplicht het invullen van title en status. Vul ook het instance veld in om support te vergemakkelijken.

  • De instance parameter dient een URI te zijn volgens de RFC-specs. Gebruik een URN in de vorm van urn:<service-uri>:[<applicatie>]:<error-instance-id>. De bron-API kan hier vrij invulling aan geven.

  • De error-instance-id kan een zelf gegeneerde ID zijn (gelinkt aan de fout), de transactieId of de correlatieId.

  • Bijv.: urn:be.vlaanderen.mbp:attesten:0b2506d4-14d4-446b-a7a9-3a2944b5efe9
    Een supportmedewerker kan hieruit snel afleiden dat het over de attestenapplicatie gaat in Mijn Burgerprofiel (MBP) en dat de errorreferentie 0b2506d4-14d4-446b-a7a9-3a2944b5efe9 is.

Specifieke foutberichten

400 Bad Request

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.

Referentie

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400

Voorbeeld

401 Unauthorized

Context

Het authenticatietoken van de gebruiker is ongeldig voor deze resource.

Referentie

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401

Voorbeeld

403 Forbidden

Context

De gebruiker is correct geauthenticeerd maar heeft geen toegang tot de resource.

Referentie

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403

Voorbeeld

404 Not Found

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.

Referentie

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404

Voorbeeld

500 Internal Server Error

Context

Foutcode bij onverwachte fouten in de service die niet worden opgevangen door andere foutcodes.

Referentie

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500

Voorbeeld

Security

TLS 1.2

Alle connecties moet over https. Gebruik hiervoor TLS 1.2 (Transport Layer Security) of hoger.

Authenticatie en autorisatie

Standaard verwachten we een Bearer-token in de Authorization header. Meer informatie over Bearer-tokens staat hier.

De structuur van de header: Authorization: Bearer <token>

ACM OAuth met burgeridentificatie

Hiervoor integreren we met het Vlaams Toegangsbeheer (ACM): https://overheid.vlaanderen.be/ict/ict-diensten/toegangsbeheer

Start hiervoor als resourceserver een dossier bij ACM en configureer een trustrelatie met Mijn Burgerprofiel. Zo kan Mijn Burgerprofiel een token exchange uitvoeren waarbij de burgerauthenticatie doorvloeit naar de bron.

De bron ontvangt een OAuth-token dat via introspection gevalideerd moet worden. De introspection zal ook extra claims teruggeven zoals rrn, given_name en family_name waarmee de bron zowel de applicatie als de burger kan identificeren.

Neem contact met ons op om deze aansluiting te starten via aansluitingen.mijnburgerprofiel@vlaanderen.be.

MBP OIDC ID Token

Hiervoor integreren we met het Vlaams Toegangsbeheer (ACM): https://overheid.vlaanderen.be/ict/ict-diensten/toegangsbeheer en de MBP ID Token Generator (IDTG).

Deze integratie is gebaseerd op OpenID Connect en de autorisatiecodeflow. De tokenset van ACM wordt via de MBP ID Token Generator omgezet naar een ID Token. Hierdoor kunnen bestaande integraties met minimale aanpassingen de bestaande ACM OIDC ID Token integratie verder gebruiken.

Checks om het token te valideren

API's moeten het token met de nodige zorg valideren door de onderstaande checks uit te voeren. De meeste van deze checks gebeuren automatisch - of kunnen makkelijk ingesteld worden.

De meeste OIDC-clients ondersteunen OIDC Auto Discovery. Stel dan alleen de autodiscovery-URL in i.p.v. elke URL apart. Dit maakt de implementatie van de OIDC-integratie minder foutgevoelig.

 

  • Controleer de cryptografische handtekening in het Bearer token aangeleverd in the Authorization header. Gebruik hiervoor de publieke JWKS-endpoint van ACM. De keys kunnen tijdelijk gecachet worden. De JWKS-endpoints zijn beschikbaar op de onderstaande URLS. Refresh de keys bij een ongekende kid. Zie ook de OIDC specs.

    • TNI: https://tni.idtokengenerator.burgerprofiel.dev-vlaanderen.be/op/jwks

    • PROD: https://idtokengenerator.burgerprofiel.vlaanderen.be/op/jwks

 

  • Controleer de geldigheid van het token in de tijd. Neem een kleine marge (skew) om false-positives te voorkomen. Niet alle klokken lopen tot op de seconde gelijk!

    • Controleer de iat (issued at)-claim, deze kan niet na het huidige tijdstip zijn

    • Controleer de exp (expiration)-claim, deze mag niet voor het huidige tijdstip zijn

 

  • Controleer de audience van het token. Dit kan een lijst met waarden zijn en zou minstens de audience voor Mijn Burgerprofiel moeten bevatten:

    • TNI: 80689076-8c4a-4bef-abc4-82805e17988d

    • PROD: 88f04968-d331-4ae0-99d9-c6efb845841f

 

  • Controleer de uitgever van het token, de issuer:

    • TNI: https://tni.idtokengenerator.burgerprofiel.dev-vlaanderen.be/op

    • PROD: https://idtokengenerator.burgerprofiel.vlaanderen.be/op

 

  • Controleer of het rijksregisternummer voor de aanvraag, dit is de rrn-claim in het token. De waarden moeten - na het strippen van spaties, punten en streepjes - exact gelijk zijn om te voorkomen dat gebruikers data ophalen van andere burgers.

 

Waarom een ID-token en geen access token?

Het ID-token betekent een impliciete autorisatie: alleen de burger kan de flow starten. De autorisatie zelf is echter niet zeker. Die is er alleen omdat een burger toegang heeft tot al zijn/haar persoonlijke informatie.

Whitelisting

Filter op basis van DNS-naam

Uitgaande connecties in Mijn Burgerprofiel zijn gefilterd op basis van de DNS-naam. Geef voor de test- en productie-omgevingen de domeinnamen op waarnaar er geconnecteerd moet worden.

Bijv: https://api.basisregisters.vlaanderen.be

IP-filter

Is er IP-filtering actief in test- en/of productie-omgevingen, whitelist dan volgende IP's:

  • 52.211.93.92

  • 34.254.120.143

  • 34.246.197.100

Performantie en loadtesten

De performantie-eisen zijn verschillend per service. Gebruik de onderstaande tabel als algemene leidraad:

Requests per seconde

30

Requests per seconde

30

Parallelle gebruikers

30

Gemiddelde respons tijd

1 sec

90 percentiel

2 sec

95 percentiel

3 sec

Max error rate

< 1%

De loadtest duurt 20 minuten, waarbij tijdens de eerst 5 minuten een ramp-up gebeurt.
Deze loadtesten gebeuren bij voorkeur op een omgeving waar Digitaal Vlaanderen controle heeft over de authenticatie-tokens.

Bezorg ons vooraf een lijst met voorbeelddata om te bevragen, meestal in de vorm van een CSV met testrijksregisternummers.

Dit is een officiële website van de Vlaamse overheid - Uitgegeven door Digitaal Vlaanderen: https://www.vlaanderen.be/digitaal-vlaanderen

DISCLAIMER: http://www.vlaanderen.be/nl/disclaimer
TOEGANKELIJKHEID: http://www.vlaanderen.be/nl/toegankelijkheid