API-DESIGN

OpenAPI Cursor & Offset Pagination Schema Example

How to declare query parameters and response pagination wrapper metadata in OpenAPI specifications.

Problem Statement

Collection endpoints without pagination parameters risk server timeout crashes when returning large datasets.

❌ Anti-Pattern / Bad Implementation

Collection endpoint returning array without limit/offset or cursor parameters.

bad-pattern.yaml

paths:
  /v1/orders:
    get:
      responses:
        '200':
          description: List of orders

✓ Refactored / Recommended Implementation

Cursor-based pagination with limit and starting_after parameters.

good-pattern.yaml

paths:
  /v1/orders:
    get:
      summary: List orders with cursor pagination
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: starting_after
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Paginated orders payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  has_more:
                    type: boolean

How APIForge Checks This

Analyzes collection endpoint parameters
Verifies response wrapper schemas

Test your own OpenAPI specification against these checks

Paste any OpenAPI specification URL or YAML file into APIForge for instant 0-100 quality scoring, schema linting, and zero-CORS proxy testing.

Run API Score Check →

Share:𝕏 Post in Share