- 1.1 Over deze documentatie
- 1.2 Gerelateerde standaarden en richtlijnen
- 1.3 REST URL-vormrichtlijnen
- 1.4 API-designrichtlijnen
- 1.5 Collecties
  - 1.5.1 Paginering
  - 1.5.2 Metadata
  - 1.5.3 Links
- 1.6 Headers
- 1.7 Authorization
  - 1.7.1 Voorbeeld
- 1.8 CorrelationId en RequestId
  - 1.8.1 CorrelationId
  - 1.8.2 RequestId
    - 1.8.2.1 Voorbeeld
- 1.9 Standaard foutberichten
  - 1.9.1 Over foutberichten
  - 1.9.2 Over responscodes
- 1.10 Specifieke foutberichten
  - 1.10.1 400 Bad Request
    - 1.10.1.1 Context
    - 1.10.1.2 Referentie
    - 1.10.1.3 Voorbeeld
  - 1.10.2 401 Unauthorized
    - 1.10.2.1 Context
    - 1.10.2.2 Referentie
    - 1.10.2.3 Voorbeeld
  - 1.10.3 403 Forbidden
    - 1.10.3.1 Context
    - 1.10.3.2 Referentie
    - 1.10.3.3 Voorbeeld
  - 1.10.4 404 Not Found
    - 1.10.4.1 Context
    - 1.10.4.2 Referentie
    - 1.10.4.3 Voorbeeld
  - 1.10.5 500 Internal Server Error
    - 1.10.5.1 Context
    - 1.10.5.2 Referentie
    - 1.10.5.3 Voorbeeld
2 Security
- 2.1 TLS 1.2
- 2.2 Authenticatie en autorisatie
  - 2.2.1 ACM OAuth met burgeridentificatie
  - 2.2.2 MBP OIDC ID Token
    - 2.2.2.1 Checks om het token te valideren
    - 2.2.2.2 Waarom een ID-token en geen access token?
- 2.3 Whitelisting
  - 2.3.1 Filter op basis van DNS-naam
  - 2.3.2 IP-filter
3 Performantie en loadtesten

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:

De OSLO-standaarden (data.vlaanderen.be) vormen de basis voor overheidsinformatie. Het is soms verplicht, maar altijd aanbevolen, om de data volgens deze afspraken te ontsluiten.
De URI-standaard voor persistente identificatoren. Dit is een technische standaard om data via persistente identificatoren te ontsluiten.
De OSLO Generieke Hypermedia driven API's, zie GitHub - Informatievlaanderen/generieke-hypermedia-api: Bouwen van een specificatie van generieke bouwblokken voor API’s in Vlaanderen. Hypermedia-driven (Hypermedia As The Engine Of Application State, kort HATEOAS) betekent dat de API zelf-documenterend is en geëxploreerd kan worden door machines. Deze standaard vult de afspraken aan voor specifieke topics.
RFC 7807 Problem Details for HTTP API's: https://tools.ietf.org/html/rfc7807

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

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.

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

Algemene REST API-specificaties

Over deze documentatie

Gerelateerde standaarden en richtlijnen

REST URL-vormrichtlijnen

API-designrichtlijnen

Collecties

Paginering

Metadata

Links

Headers

Authorization

Voorbeeld

CorrelationId en RequestId

CorrelationId

RequestId

Voorbeeld

Standaard foutberichten

Over foutberichten

Over responscodes

Specifieke foutberichten

400 Bad Request

Context

Referentie

Voorbeeld

401 Unauthorized

Context

Referentie

Voorbeeld

403 Forbidden

Context

Referentie

Voorbeeld

404 Not Found

Context

Referentie

Voorbeeld

500 Internal Server Error

Context

Referentie

Voorbeeld

Security

TLS 1.2

Authenticatie en autorisatie

ACM OAuth met burgeridentificatie

MBP OIDC ID Token

Checks om het token te valideren

Waarom een ID-token en geen access token?

Whitelisting

Filter op basis van DNS-naam

IP-filter

Performantie en loadtesten

Related pages