Pagination
Page through list endpoints with page and per_page, and read the paginator envelope.
List endpoints are paginated. Control the window with two query parameters, and
read the position from the paginator object returned in data.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer ≥ 1 | 1 | The page number to return. |
per_page | integer ≥ 1 | 20 | How many items per page. |
GET https://api.flavours.sa/dev/api/v2/products?page=2&per_page=25API-TOKEN: <your-key>X-API-Version: 2.0.0No maximum per_page is enforced
per_page only has to be a positive integer — there is no server-side cap. A
very large value asks the database for that many rows in one query, which is
slow and memory-heavy. Keep pages reasonably small (25–100) and iterate with
page.
The paginator response
data is the paginator itself: the rows are under data.data, and the position
fields sit alongside it (not nested under a separate meta).
{
"meta": {
"code": 200,
"status": "success",
"message": "Product list retrieved successfully."
},
"data": {
"current_page": 2,
"data": [
{
"id": "45dabf0e-3efa-4c64-8b8b-8f831b23d453",
"name_en": "Cappuccino"
}
],
"first_page_url": "https://api.flavours.sa/dev/api/v2/products?page=1",
"from": 26,
"last_page": 17,
"last_page_url": "https://api.flavours.sa/dev/api/v2/products?page=17",
"next_page_url": "https://api.flavours.sa/dev/api/v2/products?page=3",
"path": "https://api.flavours.sa/dev/api/v2/products",
"per_page": 25,
"prev_page_url": "https://api.flavours.sa/dev/api/v2/products?page=1",
"to": 50,
"total": 412
}
}| Field | Description |
|---|---|
data.data | The array of items for this page. |
current_page | The page you are on. |
per_page | Items per page (echoes your request, default 20). |
total | Total items across all pages. |
last_page | The number of the final page. |
from / to | The 1-based index range of items on this page (null when the page is empty). |
next_page_url / prev_page_url | Full URL of the adjacent page, or null at the ends. |
first_page_url / last_page_url | Full URLs of the first and last pages. |
path | The endpoint URL without the page query. |
Detecting the last page
You are on the last page when current_page === last_page, or equivalently when
next_page_url is null. Loop until then, incrementing page.
Paging through every item
page = 1
loop:
GET /v2/products?page={page}&per_page=100
process data.data
if data.next_page_url is null: stop
page = page + 1A note on links[]
Some list responses also include a links array — the numbered page links a UI
would render (« Previous, 1, 2, Next »). Prefer the explicit
next_page_url / last_page fields for programmatic paging; links is for
building pagination controls.