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.
Lijst met attesten
Dit is het belangrijkste endpoint dat u moet voorzien. Het moet zorgen voor een lijst met attesten en vergunningen die bij de aangemelde gebruiker horen, en de details over die attesten en vergunningen. De gebruiker wordt geïdentificeerd op basis van zijn/haar INSZ-nummer. Zie ook de OpenAPI-specificaties voor meer informatie.
Er moeten links worden voorzien zodat de klant door de verschillende pagina’s met attesten en vergunningen kan navigeren. Zie ook HATEOAS voor meer informatie en voorbeelden.
De respons moet altijd een paginering hebben. De metadata bij de pagina’s moet deel uitmaken van de payload zodat de klant weet hoeveel attesten en vergunningen er zijn, op welke pagina’s die staan, enz. Zie ook de voorbeelden hieronder.
The URL heeft een
page-parameter, die 0-based moet zijn. Zodra 0 is gepasseerd, moet de eerste pagina worden meegegeven.In de metadata van de pagina is er echter niets 0-based, alleen 1-based. Bijv. de
number-parameter moet op de eerste pagina de waarde 1 hebben.
Model-specifieke informatie
certificates (verplicht): lijst met attesten, eigenlijk een lijst met detailinformatie over de attesten en vergunningen (zie hieronder).
Worden er geen attesten of vergunningen gevonden voor het INSZ-nummer, dan moet de lijst leeg zijn.
Request (voorbeeld)
Headers: Authorization: Bearer XyZAbCd1234
Method: GET
URL https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0