...
Het is relatief eenvoudig om nieuwe bronnen voor attesten en vergunningen toe te voegen op Mijn Burgerprofiel. Aansluitende partijen/partners die Als aansluitende partij/partner is voldoen aan deze API-specificaties kunnen de voorwaarde om na een korte configuratie hun attesten en vergunningen beschikbaar te maken in Mijn Burgerprofiel.
Aansluiten kan via dit aanvraagformulier.
OpenAPI-specificaties
Download de OpenAPI-specificaties.
...
Layout
URL's en versiebeheer
We raden u aan om ons voorbeeld te volgen en Voeg altijd 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.
...
| Note |
|---|
Digitaal Vlaanderen vertaalt alleen de velden in de OpenAPI-specificaties. |
Lijst met attesten
...
/vergunningen
De lijst met attesten is het belangrijkste endpoint dat u moet om te voorzien. Dit endpoint moet zorgen Het zorgt voor een lijst met attesten en vergunningen die bij de aangemelde gebruiker horen, inclusief de details over die attesten en vergunningen. De gebruiker wordt geïdentificeerd op basis van zijn/haar INSZ-nummer.
...
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 response 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 codevoorbeelden hieronder.
DE 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.
...
| Note |
|---|
Worden er geen attesten of vergunningen gevonden voor het INSZ-nummer, dan moet de lijst leeg zijn. |
Request (voorbeeld)
HeadersHeader:
Authorization: Bearer XyZAbCd1234Method: GET
URL URL:
https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0
...
Er kan natuurlijk een maximumwaarde worden bepaald. We raden aan om Werk bij voorkeur met een maximumwaarde van 100 items te werken. Vraagt de client om meer resultaten dan die in de maximumwaarde, dan wordt de default maximumwaarde getoond.
...
Bij gebrek aan defaults voor de paginering (page) en maximumwaarde (limit) moet de API terugvallen op redelijk redelijke defaults.De onderstaande requests zijn dus perfect bruikbaar:
https://<hostname>/v1/certificates/<ssn>?limit=10&page=0https://<hostname>/v1/certificates/<ssn>?limit=10https://<hostname>/v1/certificates/<ssn>?page=0
Worden er geen defaultwaarden gedefinieerd, gebruik dan deze logische defaultsdefaultwaarden:
page: de eerste paginalimit: 10
...
Metadata voor paginering zijn verplicht in het pageMetadata-object in van de response:
| Code Block |
|---|
"pageMetadata": {
"number": 1,
"size": 10,
"totalElements": 40,
"totalPages": 4
} |
De volgende 4 parameters zijn verplicht (allemaal 1-based)
number: het paginanummersize: het paginanummer in het totaal aantal pagina’stotalElementshet : het totale aantal items in de collectietotalPageshet : het totale aantal pagina’s in de collectie
...
Wanneer er voor een bepaald INSZ-nummer geen attesten of vergunningen worden gevonden, verwachten we een lege collectie als antwoord, geen error 404.
Zie ook de Foutberichten.
...
Dit is de link waarachter meer details over een attest/vergunning beschikbaar zijn. Deze link zorgt ervoor dat de klant bepaalde functionaliteiten kan vinden, zoals bijv. het attest/de vergunning downloaden.
Zie ook HATEOS.
| Note |
|---|
Er kunnen extra velden worden toegevoegd in de response, maar ze zullen niet meegenomen worden. |
Primary key
Dit zijn de parameters die het attest/de vergunning definiëren. Voor een attest is de primary key: ID + taal. Beide moeten dus in de URL staan. Afhankelijk van de opzet zijn dit path parameters of query parameters.
In de voorbeelden zijn het path parameters. Omdat we een HATEOAS-design verwachten, vinden we de URL via uw API.
...
id (verplicht): het ID van het attest/de vergunning
taal (verplicht): de taal van het attest/de vergunning, verplicht in ISO639-1 formaat:
nl,fr,de,en. Zie ook: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes .naam (verplicht): de naam van het attest/de vergunning
jaar (optioneel): het jaar dat het attest/de vergunning werd uitgegeven (indien van toepassing)
community (optioneel): de gemeente waar het attest/de vergunning werd uitgegeven (indien van toepassing). Dit moet een NIS-code zijn. Zie ook: https://statbel.fgov.be/nl/over-statbel/methodologie/classificaties/geografie
Request (voorbeeld)
HeadersHeader:
Authorization: Bearer XyZAbCd1234Method: GET
URL URL:
https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl
...
Als de specificaties worden gevolgd, zijn alle API’s conform HATEOAS (Hypermedia As The Engine Of Application State). Waarom is dit zo belangrijk? Deze architecturale component zorgt ervoor dat een REST-client de API altijd volledig ontdektleest, zonder voorafgaande veronderstelde kennis. Alleen Hiervoor is alleen het entrypoint van de API is hiervoor nodig. Van daar kan Dan endpoint is het startpunt van waar de client door de API kan ‘crawlen’ door relaties (rels) en referenties (hrefs) te gebruiken.
Bij Digitaal Vlaanderen kunnen we dankzij HATEOAS uw API volledig ontdekken uitlezen zonder een client te schrijven met specifieke kennis over uw API.
...
Volg de onderstaande voorbeelden. Voeg HATEOAS toe aan uw uw API door de links-sectie toe te voegen. De links-sectie moet beschikbaar zijn voor de lijst met attesten/vergunningen en bij de details van een specifiek attest/vergunning.
Links-
...
sectie
Een links-sectie voor een lijst attesten/vergunningen ziet er gewoonlijk als volgt uit:
...
De volgende 4 verschillende relaties moeten aanwezig zijn verplicht:
self(verplicht) : de href-verwijzingen naar de huidige paginanext: (verplicht op voorwaarde dat er meerdere pagina’s zijn) de href-verwijzingen naar de volgende pagina in de gepagineerde collectie. Moet er , alleen zijn nodig als er effectief een volgende pagina is om naar te verwijzenstart(verplicht) : de href-verwijzing naar de eerste pagina van de collectie to the start page of the collection.last(verplicht) de : de href-verwijzing naar de laatste pagina van de collectie
...
De volgende 2 verschillende relaties moeten aanwezig zijn verplicht:
self(verplicht) de href-verwijzing naar de detailinformatie bij het attest/vergunningdownload(verplicht) de href-verwijzing naar de downloadlink bij het attest/vergunning. Dit moet een directe link zijn, die gestreamd kan worden naar de gebruiker.
...