Documentatie voor klanten en partners van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers
Algemene REST API-specificaties
- 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
- 1.10.1 400 Bad Request
- 2 Security
- 2.1 TLS 1.2
- 2.2 Authenticatie en autorisatie
- 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 https://github.com/Informatievlaanderen/generieke-hypermedia-api. 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 |
---|---|
Datum & tijd |
De volgende zijn correct:
Formaten zonder tijdszone-indicatie worden NIET geaccepteerd, bv: |
Payload |
|
HTTP-statuscodes | Maak overwogen gebruik van HTTP Statuscodes en beperk waar mogelijk tot een subset. Zie de Expertise Groep Architectuur richtlijnen en https://tools.ietf.org/html/rfc2616#section-9.5 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 |
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 paginasize
(verplicht) het aantal objecten teruggegeven op deze paginatotalItems
(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 opgegevenhref
wijst naar de huidige pagina van de collectie.next
(alleen als er een volgende pagina is) de opgegevenhref
wijst naar de volgende pagina van de collectie, alleen als er effectief een volgende pagina isprev
(enkel er een vorige pagina is) de opgegevenhref
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 (bva6d87d0e-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 (bv0d1e63a3-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 gefaald401 Unauthorized
Het authenticatietoken van de gebruiker is verlopen403 Forbidden
De gebruiker heeft geen toegang tot de resource404 Not Found
De specifieke resource is niet gevonden500 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 vanurn:<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 deattesten
applicatie gaat inMijn Burgerprofiel
(MBP) en dat de errorreferentie0b2506d4-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 ongekendekid
. 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 zijnControleer 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 |
---|---|
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