Specificaties Attesten en vergunningen-API

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.

Bekijk ook de algemene REST API-specificaties.

Waarom API-specificaties

Het is relatief eenvoudig om nieuwe bronnen voor attesten en vergunningen toe te voegen op Mijn Burgerprofiel. Als aansluitende partij/partner is voldoen aan deze API-specificaties de voorwaarde om na een korte configuratie attesten en vergunningen beschikbaar te maken in Mijn Burgerprofiel.

Aansluiten kan via dit aanvraagformulier.

OpenAPI-specificaties

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

Voeg altijd een versienummer toe 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/<insz>?limit=10&page=0

Verplichte velden

In de OpenAPI-specificaties vindt u een overzicht van de verplichte en de optionele velden. Indien nodig kunt u extra velden toevoegen.

Lijst met attesten/vergunningen

De lijst met attesten is het belangrijkste endpoint om te voorzien. 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. (Zie ook: https://overheid.vlaanderen.be/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 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.

Model-specifieke informatie

certificates (verplicht): lijst met attesten inclusief de 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)

Header: Authorization: Bearer XyZAbCd1234
Method: GET
URL: https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302?limit=10&page=0

respons (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 respons moet gepagineerd zijn voor elke collectie die wordt meegegeven. De volgende 2 parameters in de URL’s moeten hiervoor aanwezig zijn:

page: het paginanummer (0-based)
limit: het aantal items op 1 pagina (1-based)

Gepagineerde resultaten zijn natuurlijk alleen nodig wanneer het resultaat een collectie is. Voor 1 attest/vergunning + details is er geen 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/<insz>?limit=10&page=0. T

De API-client kan de parameter met de grenswaarde bepalen. 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 bij voorkeur 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 redelijke defaults.

https://<hostname>/v1/certificates/<insz>?limit=10&page=0
https://<hostname>/v1/certificates/<insz>?limit=10
https://<hostname>/v1/certificates/<insz>?page=0

Worden er geen defaultwaarden gedefinieerd, gebruik dan deze logische defaultwaarden:

page: de eerste pagina
limit: 10

Metadata voor paginering

Metadata voor paginering zijn verplicht in het pageMetadata-object van de respons:

"pageMetadata": {
    "number": 1,
    "size": 10,
    "totalElements": 40,
    "totalPages": 4
}

De volgende 4 parameters zijn verplicht (allemaal 1-based)

number: het paginanummer
size: het paginanummer in het totaal aantal pagina’s
totalElements: het totale aantal items in de collectie
totalPages: het totale aantal pagina’s in de collectie

Er werden geen attesten of vergunningen gevonden

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.

Detail attest/vergunning

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.

Er kunnen extra velden worden toegevoegd in de respons, 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.

Model-specifieke informatie

id (verplicht): het ID van het attest/de vergunning
language (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 .
name (verplicht): de naam van het attest/de vergunning
year (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

Digitaal Vlaanderen verwerkt alleen de velden die deel uitmaken de OpenAPI-specificaties.

Request (voorbeeld)

Header: Authorization: Bearer XyZAbCd1234
Method: GET
URL: https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl

respons (voorbeeld)

{
  "id": "85144567-7043-4469-9e79-279f4eb31e27",
  "language" : "nl",
  "name": "certificate-1234",
  "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"
    }
  ]
}

HATEOAS

Over HATEOAS

Als de specificaties worden gevolgd, zijn alle API’s conform HATEOAS (Hypermedia As The Engine Of Application State). Deze architecturale component zorgt ervoor dat een REST-client de API altijd volledig leest, zonder veronderstelde kennis. Hiervoor is alleen het entrypoint van de API nodig. 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 uitlezen zonder een client te schrijven met specifieke kennis over uw API.

Hoe implementeren?

Volg de onderstaande voorbeelden. Voeg HATEOAS toe aan 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:

"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=1"
    }
]

De volgende 4 verschillende relaties zijn verplicht:

self: de href-verwijzingen naar de huidige pagina
next: (verplicht op voorwaarde dat er meerdere pagina’s zijn) de href-verwijzingen naar de volgende pagina in de gepagineerde collectie, alleen nodig als er effectief een volgende pagina is om naar te verwijzen
start: de href-verwijzing naar de eerste pagina van de collectie
last: de href-verwijzing naar de laatste pagina van de collectie

Links - detailinformatie attesten/vergunningen

Een links-sectie voor de detailinformatie bij de attesten/vergunningen ziet er gewoonlijk als volgt uit:

"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"
    }
]

De volgende 2 verschillende relaties zijn verplicht:

self (verplicht) de href-verwijzing naar de detailinformatie bij het attest/vergunning
download (verplicht) de href-verwijzing naar de downloadlink bij het attest/vergunning. Dit moet een directe link zijn, die gestreamd kan worden naar de gebruiker.

Security

De security-vereisten, zoals opgesteld in de Algemene REST API-specificaties - Security, gelden ook voor de Attesten en vergunningen-API.

Performantie en loadtesten

De API dient te voldoen aan de vereisten zoals opgesteld in de Algemene REST API specificaties - Performantie en loadtesten.

Documentatie voor klanten en partners van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers">Documentatie voor klanten en partners van Digitaal Vlaanderen - bouwstenen Mijn Burgerprofiel, Verenigingsloket en e-loketondernemers

Specificaties Attesten en vergunningen-API

Over deze documentatie

Waarom API-specificaties

OpenAPI-specificaties

JSON

Layout

URL's en versiebeheer

Verplichte velden

Lijst met attesten/vergunningen

Model-specifieke informatie

Request (voorbeeld)

respons (voorbeeld)

Paginering en maximumwaarden

Paginering verplicht

De API-client kan de maximumwaarde kiezen

Er werden geen default-waarden gedefinieerd

Metadata voor paginering

Er werden geen attesten of vergunningen gevonden

Detail attest/vergunning

Primary key

Model-specifieke informatie

Request (voorbeeld)

respons (voorbeeld)

HATEOAS

Over HATEOAS

Hoe implementeren?

Links-sectie

Links - detailinformatie attesten/vergunningen

Security

Performantie en loadtesten