[ADP-312] Pagination

reviewing phase 1

Correct OpenAPI examples

Overview

Pagination in RESTful APIs is a technique for dividing large datasets into smaller, more manageable chunks or "pages." This helps improve performance, reduce server load, and provide a better user experience.

There are mainly two methods of pagination: offset-based pagination and cursor-based pagination.

Offset-based Pagination

Offset-based pagination uses an offset value to specify the starting point of the dataset and a limit to specify the number of items to retrieve.

Example

GET /resources?offset=20&limit=10 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
Link: </resources?offset=20&limit=10>; rel="self", </resources?offset=30&limit=10>; rel="next", </resources?offset=10&limit=10>; rel="prev", </resources?offset=0&limit=10>; rel="first", </resources?offset=90&limit=10>; rel="last"
X-Total-Count: 100

{
  "resources": [ /* Resources from offset 20 to 29 */ ],
  "meta": {
    "offset": 20,
    "limit": 10,
    "totalItems": 100
  }
}

Cursor-based Pagination

Cursor-based pagination uses a cursor (usually a unique identifier) to fetch the next set of results.

Example

GET /resources?cursor=abc123&limit=10 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
Link: </resources?cursor=abc123&limit=10>; rel="self", </resources?cursor=def456&limit=10>; rel="next"
X-Total-Count: 256

{
  "resources": [ /* Resources starting after cursor abc123 */ ],
}

Guidance

• You SHOULD choose a pagination convention and use common query parameters for pagination. Currently, cursor-based pagination is more common.

• You SHOULD use common query parameters for pagination, namely: cursor, offset, limit.

• You SHOULD provide pagination information using standard Link headers according to RFC 8288 instead of embedding links in the response body.

  HTTP/1.1 200 OK
  Content-Type: application/json
  Link: </resources?cursor=abc123&limit=10>; rel="self",
        </resources?cursor=def456&limit=10>; rel="next",
        </resources?cursor=xyz789&limit=10>; rel="prev",
        </resources?cursor=first&limit=10>; rel="first",
        </resources?cursor=last&limit=10>; rel="last"
  X-Total-Count: 256
  
  {
    "resources": [
      /* Resource items */
    ]
  }

• You SHOULD use custom headers for additional pagination metadata, such as total count. These headers MUST be registered in the organization's internal registry.

  • X-Total-Count: The total number of items available
  • X-Page-Count: The total number of pages available
  • X-Current-Page: The current page number

Example

OpenAPI Example

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
paths:
  /resources:
    get:
      summary: Retrieve resource list
      parameters:
        - name: cursor
          in: query
          description: Cursor for pagination
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: filter
          in: query
          description: Filtering criteria
          required: false
          schema:
            type: string
        - name: sort
          in: query
          description: Sorting order
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Paginated resource list
          headers:
            Link:
              description: Pagination links following RFC 8288
              schema:
                type: string
              example: </resources?cursor=def456&limit=10>; rel="next", </resources?cursor=xyz789&limit=10>; rel="prev"
            X-Total-Count:
              description: Total number of items available
              schema:
                type: integer
              example: 256
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object

References

Specification References

• RFC 8288: Web Linking

Design References

• GitHub API Pagination
• Zalando RESTful API Guidelines

Changelog

• 2025-04-14: Updated to recommend standard Link headers and custom headers for pagination metadata instead of embedding links in response body.