| Table of Contents | ||||
|---|---|---|---|---|
|
OpenAPI
...
-specificaties
Download de OpenAPI-specificaties.
Attesten-API
This documentation contains the API description that is expected from a source of certifcates that is supplying certificates to the Burgerprofiel platform of the Flemish GovernmentIn 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 de API-specificaties kunnen na een korte configuratie hun attesten en vergunningen beschikbaar maken in Mijn Burgerprofiel.
JSON
We standardize on application/hal+json. This specific form of JSON flags that the payload is HATEOAS compliant.
Layout
URL's and versioning
We advise you to follow our example, and put a version in the URL. Debates are going on strongly about whether or not to use a v1 in your URL, but it is a pragmatic choice we implement in our API's. The version parameter is always a natural number, ie v1, v2, ... Within a certain version, breaking changes can never occur. If you introduce breaking changes, the next version should be released.
A typical URL for your endpoint would look like: https://<hostname>/v1/certificates/<ssn>?limit=10&page=0
Required fields
We have carefully documented which fields are optional, and which are not. Please refer to the OpenAPI documentation of the API for more information.
If you want, more fields can be added. We will not interpret them, however. We only interpret the fields that we have specified in the specification.
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