Page Comparison

...

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

...

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

...

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

The API should fall back to sensible defaults if a client does not provide the page and limit parameters.

That means that these requests are all perfectly validBij 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

When the parameters are not provided, we suggest to use these defaults:

• page: when the page parameter is not present, the most logic choice is to return the first page.

• limit: when the limit parameter is not present, you can fall back to a sensible default - we suggest you use 10.

Paginametadata

You are required to provide metadata on the paging. This is done via a pageMetadata object in the response: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
}

We expect the object to contain 4 parameters:

• number (required) the number of the page. This is a 1-based parameter.

• size (required) the number of the page in the total number of pages. This is a 1-based parameter.

• totalElements (required) the total number of elements in the collection. This is a 1-based parameter.

• totalPages (required) the total number of pages in the collection. This is a 1-based parameter.

No certificates found

When no certificates can be found for a certain SSN, we expect an empty collection as a return, not an error 404 (for more details, refer to Error Messages).

Certificate detail

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)