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
Bij gebrek aan defaults voor de paginering (page
) en maximumwaarde (limit)
moet de API terugvallen op redelijk defaults.
De onderstaande requests zijn dus perfect bruikbaar:
https://<hostname>/v1/certificates/<ssn>?limit=10&page=0
https://<hostname>/v1/certificates/<ssn>?limit=10
https://<hostname>/v1/certificates/<ssn>?page=0
Worden er geen defaultwaarden gedefinieerd, gebruik dan deze logische defaults:
page
: de eerste paginalimit
: 10
Metadata voor paginering
Metadata voor paginering zijn verplicht in het pageMetadata
-object in de response:
"pageMetadata": { "number": 1, "size": 10, "totalElements": 40, "totalPages": 4 }
We expect the object to contain 4 parameters:
number
(required) the number of the page. This is a 1-based parameter.size
(required) the number of the page in the total number of pages. This is a 1-based parameter.totalElements
(required) the total number of elements in the collection. This is a 1-based parameter.totalPages
(required) the total number of pages in the collection. This is a 1-based parameter.
No certificates found
When no certificates can be found for a certain SSN, we expect an empty collection as a return, not an error 404 (for more details, refer to Error Messages).
Certificate detail
Behind this link, more information about a certain certificate can be found.
Links have to be provided for the client to be able to discover specific functionalities, for example: downloading the certificate. For more information, refer to the HATEOAS section and the examples.
As said, you can add more fields here to the response, if you like. We will not interpret them, however.
Primary key
Important to note here are the parameters that define a certificate. The primary key of a certificate is its ID + its language. That means that both have to be in the URL. It depends on your own design whether these are path parameters or query parameters.
Our examples define them as path parameters. The choice is yours, however. Since we expect a HATEOAS design, we will simply discover the URL via your API.
Model specifics
id (required): the ID of the certificate.
language (required): the language of the certificate. Should be in ISO639-1 format. More information: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes . Expected 1 of these 4:
nl
,fr
,de
,en
.name (required): name of the certificate
year (optional): year when the certificate was handed out (if applicable)
community (optional): community where the certificate handed out (if applicable). Should be a NIS code. More information https://statbel.fgov.be/nl/over-statbel/methodologie/classificaties/geografie
Request (example)
Headers: Authorization: Bearer XyZAbCd1234
Method: GET
URL https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl