Page Comparison

...

Er moeten links worden voorzien zodat de klant 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 klant client weet hoeveel attesten en vergunningen er zijn, op welke pagina’s die staan, enz. Zie ook de voorbeelden hieronder.

...

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

As stated above, we require that the response is paginated when you return a collection. In the URL's, this is shown by the presence of two parameters:

• page: defines the page number (0-based)

• limit: defines the number of items on a single page (evidently, 1-based)

Paged returns are, evidently, only required when you return a collection. A detail of a single certificate does not require a paged return.

De API-client kan de maximumwaarde kiezen

The page and limit parameters are present in the URL: https://<hostname>/v1/certificates/<ssn>?limit=10&page=0. The limit parameter can be directed by the client of the API. If the client asks for 10 items, 10 should be returned. If the client wants 50 results, 50 should be returned.

This can have a sensible upper limit, however. Our suggestion would be to use 100 results as the upper limit. That means that if a client asks for more than the upper limit, you default back to the upper limit you defined.

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 valid:

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