Pagination

At a glance#

A list operation returns one page at a time. The request names the page and its size; the response carries the page, the total and the links in the body, never in a header.

pageNumber, pageSize, page_number, page_size, size, limit, offset and cursor are not the platform's names for paging. An API that needs cursor paging for a very large collection says so in its description and still offers page and per_page.

The response#

{
  "data": [
    { "order_id": "ord_1042", "status": "shipped" },
    { "order_id": "ord_1043", "status": "open" }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 12,
    "per_page": 15,
    "total": 172
  },
  "links": {
    "first": "https://gate.api360.sa/<product-slug>/v1/orders?page=1&per_page=15",
    "next": "https://gate.api360.sa/<product-slug>/v1/orders?page=2&per_page=15",
    "prev": null,
    "last": "https://gate.api360.sa/<product-slug>/v1/orders?page=12&per_page=15"
  }
}

• data is an array, empty when the page holds nothing. A page after the last answers 200 with an empty data, not 404.
• meta.total is the number of items in the whole collection. A client that needs a count never reads a header or counts pages.
• An API that wraps every answer in success, message and data, as the platform's console API does, puts the page one level down: data.data and data.meta. The rule accepts both shapes.

Limits#

A per_page above the maximum is answered with 400 and the error envelope. Clamping silently hides the mistake from the caller. A page or per_page below 1 is also 400.

The maximum is a safety limit as well as a contract: without it a caller can ask for the whole table in one request.

Checked by#

See also#

• Errors: the 400 for a bad per_page.
• Naming: sort_by and sort_dir are snake_case too.