Specificaties Attesten en vergunningen

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.

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.

Model-specifieke informatie

• certificates (verplicht): lijst met attesten, eigenlijk een lijst met detailinformatie over de attesten en vergunningen (zie hieronder).

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.

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 pagina

• limit: 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
}

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. <voeg link toe naar foutberichten in de API specs>

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

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

Response (example)

HATEOAS