API Pagination

Offset-Based

Use an offset and a limit parameter to define the starting point and the number of records to return.

Request

GET /api/v1/users?offset=0&limit=10

Response

{
  "data": [
    {
      "id": 1,
      "name": "William Gopallawa"
    },
    {
      "id": 2,
      "name": "Junius Richard Jayewardene"
    },
    ...
  ],
  "meta": {
    "offset": 0,
    "limit": 10,
    "total": 100
  }
}

Cursor-Based

Use a cursor (a unique identifier) to mark the position in the dataset

Request

GET /api/v1/users?cursor=eyJpZCI6MX0&limit=10

Response

{
  "data": [
    {
      "id": 2,
      "name": "Junius Richard Jayewardene"
    },
    {
      "id": 3,
      "name": "Ranasinghe Premadasa"
    },
    ...
  ],
  "meta": {
    "cursor": "eyJpZCI6Mn0",
    "limit": 10,
    "total": 100
  }
}

Page-Based

Use a page number and a page size to define the page and the number of records to return.

Request

GET /api/v1/users?page=1&size=10

Response

{
  "data": [
    {
      "id": 1,
      "name": "William Gopallawa"
    },
    {
      "id": 2,
      "name": "Junius Richard Jayewardene"
    },
    ...
  ],
  "meta": {
    "page": 1,
    "size": 10,
    "total": 100
  }
}

Keyset-Based

Use the last record's key to fetch the next set of records.

Request

GET /api/v1/users?lastKey=2&limit=10

Response

{
  "data": [
    {
      "id": 3,
      "name": "Ranasinghe Premadasa"
    },
    {
      "id": 4,
      "name": "Dingiri Banda Wijetunga"
    },
    ...
  ],
  "meta": {
    "lastKey": 4,
    "limit": 10,
    "total": 100
  }
}

Time-Based

Use a timestamp to fetch records created after that time.

Request

GET /api/v1/users?since=2024-07-01T00:00:00Z&limit=10

Response

{
  "data": [
    {
      "id": 1,
      "name": "William Gopallawa"
    },
    {
      "id": 2,
      "name": "Junius Richard Jayewardene"
    },
    ...
  ],
  "meta": {
    "since": "2024-07-01T00:00:00Z",
    "limit": 10,
    "total": 100
  }
}

Hybrid

Use a combination of the above methods to paginate the results.

Request

GET /api/v1/users?since=2024-07-01T00:00:00Z&limit=10&cursor=eyJpZCI6MX0

Response

{
  "data": [
    {
      "id": 2,
      "name": "Junius Richard Jayewardene"
    },
    {
      "id": 3,
      "name": "Ranasinghe Premadasa"
    },
    ...
  ],
  "meta": {
    "since": "2024-07-01T00:00:00Z",
    "limit": 10,
    "cursor": "eyJpZCI6Mn0",
    "total": 100
  }
}