OpenAPI-specificaties
Download de OpenAPI-specificaties.
Over deze documentatie
In deze documentatie vindt u aan welke API-specificaties uw bron moet voldoen om attesten en vergunningen beschikbaar te maken in Mijn Burgerprofiel.
Waarom API-specificaties
Het is relatief eenvoudig om nieuwe bronnen voor attesten en vergunningen toe te voegen op Mijn Burgerprofiel. Aansluitende partijen/partners die voldoen aan deze API-specificaties kunnen na een korte configuratie hun attesten en vergunningen beschikbaar maken in Mijn Burgerprofiel.
JSON
We gebruiken application/hal+json als standaard. Deze specifieke JSON geeft aan dat de payload voldoet aan de HATEOAS-standaard.
Layout
URL's en versiebeheer
We raden u aan om ons voorbeeld te volgen en een versienummer toe te voegen aan de URL. Het versienummer is altijd een cijfer, bijv. v1, v2, … Er kunnen nooit breaking changes bestaan binnen een bepaalde versie. Zijn er toch breaking changes nodig, zorg dan voor een nieuwe versie.
Een URL voor uw endpoint kan er als volgt uitzien: https://<hostname>/v1/certificates/<ssn>?limit=10&page=0
Verplichte velden
In de de OpenAPI-specificaties vindt u een overzicht van de verplichte en de optionele velden. Indien nodig kunt u extra velden toevoegen.
Digitaal Vlaanderen vertaalt alleen de velden in de OpenAPI-specificaties.
Certificates listing
This is the most important endpoint you need to provide. It needs to return a list of certificates which are relevant for the user. The user can be identified via his/her social security number (ssn) (= INSZ/NISS). The list is essentially a list of Certificate Detail items. Refer to the OpenAPI documentation of the API for more information.
Links have to be provided for the client to be able to navigate through the different pages of the certificates. For more information, refer to the HATEOAS section and the examples.
The response needs to be paginated at all times. Page metadata should be delivered in the payload, so the client knows how many certificates there are, which page it is on, etc. Please refer to the examples.
The URL has a
pageparameter, which should be 0-based. If 0 is passed, the first page should be returned.In the page metadata, nothing is 0-based, but everything is 1-based. So, for example, the
numberparameter should have the value 1 on the first page.
Model specifics
certificates (required): list of certificates. Essentially, a list of Certificate Detail items (see below).
If no certificates can be found for the provided SSN, this should be an empty list.
Request (example)
Headers: Authorization: Bearer XyZAbCd1234
Method: GET
URL https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0