Skip to content
faker.tools
All 79

Plate IV · Developer, API & Database Seeding Utilities

Pagination Response Generator

Offset, cursor, Link header and JSON:API envelopes, including empty pages.

json
{
  "data": [
    {
      "id": 1,
      "title": "Item 1",
      "status": "pending"
    },
    {
      "id": 2,
      "title": "Item 2",
      "status": "archived"
    },
    {
      "id": 3,
      "title": "Item 3",
      "status": "archived"
    },
    {
      "id": 4,
      "title": "Item 4",
      "status": "archived"
    },
    {
      "id": 5,
      "title": "Item 5",
      "status": "archived"
    },
    {
      "id": 6,
      "title": "Item 6",
      "status": "active"
    },
    {
      "id": 7,
      "title": "Item 7",
      "status": "pending"
    },
    {
      "id": 8,
      "title": "Item 8",
      "status": "archived"
    },
    {
      "id": 9,
      "title": "Item 9",
      "status": "active"
    },
    {
      "id": 10,
      "title": "Item 10",
      "status": "archived"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 10,
    "total": 137,
    "totalPages": 14,
    "from": 1,
    "to": 10,
    "hasNext": true,
    "hasPrev": false
  },
  "links": {
    "self": "/api/v1/items?page=1&per_page=10",
    "next": "/api/v1/items?page=2&per_page=10",
    "prev": null
  }
}
69 lines · 1.1 KBGenerated in your browser · Pagination Response Generator

Pagination bugs live at the edges: the last page with three items instead of ten, the empty result set, the page number past the end. Set a total that does not divide evenly by the page size and every one of those cases appears.

What you can control

  • Four pagination styles covering the conventions in common use.
  • Page counts, offsets and navigation links are computed from the total, so the last page really is short.
  • The empty-page toggle produces the zero-result state that most list UIs never got designed for.
  • The Link header style follows RFC 8288 with first, prev, next and last relations.

Testing ideas

  • Last page. Set the current page to the last one and check that "next" is disabled and the item count is right when the final page is partial.
  • Empty page. Simulate an empty page — the state most list UIs forget to design.
  • Styles. Compare offset, cursor, RFC 8288 Link header and JSON:API styles to build a client that handles the one your API actually uses.
  • Large totals. Set 100,000 items to test page-number rendering and "showing 99,951–100,000" labels.

What this is not

Cursors are base64-encoded index strings. Real cursor pagination uses an opaque token encoding sort position, so use these for client testing rather than server design.

Questions

Which pagination style should I use?

Cursor pagination for anything where rows are inserted while a user is paging — offset pagination silently skips and repeats records when the underlying list shifts.

Why test the empty state?

Because a list component almost always ships without one, and the first customer with no data sees a blank rectangle instead of an explanation.

What is RFC 8288?

The specification for the HTTP `Link` header. It carries pagination in headers rather than in the body, which keeps the response payload to just the data.

Next in Developer

All 11 →