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 client 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 client 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
Response (voorbeeld)
{
"certificates": [
{
"id": "85144567-7043-4469-9e79-279f4eb31e27",
"language" : "nl",
"name": "Dienstencheques 2019",
"year": 2019,
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl"
},
{
"rel": "download",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl/download"
}
]
}
],
"pageMetadata": {
"number": 1,
"size": 10,
"totalElements": 40,
"totalPages": 4
},
"links": [
{
"rel": "self",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0"
},
{
"rel": "next",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=1"
},
{
"rel": "start",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0"
},
{
"rel": "last",
"href": "https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=3"
}
]
}
Paginering en maximumwaarden
Paginering verplicht
De response moet gepagineerd zijn voor elke collection die wordt meegegeven. De volgende 2 parameters in de URL’s moeten hiervoor aanwezig zijn: I
page: het paginanummers (0-based)limit: het aantal items op 1 pagina (1-based)
Gepagineerde resultaten zijn natuurlijk alleen nodig wanneer er een collectie als resultaat is. Voor 1 attest/vergunning + details is er een paginering nodig.
Worden er geen attesten of vergunningen gevonden voor het INSZ-nummer, dan moet de lijst leeg zijn.
De API-client kan de maximumwaarde kiezen
De parameters voor de paginering en de maximumwaarden maken deel uit van de URL: https://<hostname>/v1/certificates/<ssn>?limit=10&page=0. T
De API-client kan de parameter met de grenswaarde controleren. Als de client 10 items vraagt, dan moeten er 10 worden gegeven. Vraagt de client er 50, dan moeten er 50 worden gegeven.
Er kan natuurlijk een maximumwaarde worden bepaald. Werk met een maximumwaarde van 100 items. Vraagt de client om meer resultaten dan die in de maximumwaarde, dan wordt de default maximumwaarde getoond.
Er werden geen default-waarden gedefinieerd
The API should fall back to sensible defaults if a client does not provide the page and limit parameters.
That means that these requests are all perfectly valid:
https://<hostname>/v1/certificates/<ssn>?limit=10&page=0https://<hostname>/v1/certificates/<ssn>?limit=10https://<hostname>/v1/certificates/<ssn>?page=0
When the parameters are not provided, we suggest to use these defaults:
page: when the page parameter is not present, the most logic choice is to return the first page.limit: when the limit parameter is not present, you can fall back to a sensible default - we suggest you use 10.
Paginametadata
You are required to provide metadata on the paging. This is done via a pageMetadata object in the response: