Page Comparison

...

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 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 hieronder.

...

• 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)

• Headers: Authorization: Bearer XyZAbCd1234

• Method: GET

• URL https://burgerprofiel.vlaanderen.be/v1/certificates/90061638302/85144567-7043-4469-9e79-279f4eb31e27/nl

Response

...

(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). Waarom is dit zo belangrijk? Deze architecturale component zorgt ervoor dat een REST-client de API volledig ontdekt, zonder voorafgaande kennis. Alleen het entrypoint van de API is hiervoor nodig. Van daar kan de client door de API ‘crawlen’ door relaties (rels) en referenties (hrefs) te gebruiken.

Bij Digitaal Vlaanderen kunnen we dankzij HATEOAS uw API volledig ontdekken zonder een client te schrijven met specifieke kennis over uw API.

Hoe implementeren?

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 - Lijst attesten/vergunningen

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 moeten aanwezig zijn

• self (verplicht) 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. Moet er alleen zijn als er effectief een volgende pagina is om naar te verwijzen

• start (verplicht) de href-verwijzing naar de eerste pagina van de collectie to the start page of the collection.

• last (verplicht) de href-verwijzing naar de laatste pagina van de collectie

Links - Certificate Detail

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 moeten aanwezig zijn

• 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.