Pagination Patterns in OpenAPI

Pagination in OpenAPI

Any API endpoint that returns a list of items needs pagination. OpenAPI can document all major pagination patterns including offset/limit, page-based, and cursor-based approaches.

Offset/Limit Pagination

The simplest approach:

/items:
  get:
    parameters:
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
    responses:
      "200":
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: "#/components/schemas/Item"
                total:
                  type: integer
                offset:
                  type: integer
                limit:
                  type: integer

Page-Based Pagination

More user-friendly numbering:

/articles:
  get:
    parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: per_page
        in: query
        schema:
          type: integer
          default: 25
          maximum: 100
    responses:
      "200":
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaginatedArticles"

components:
  schemas:
    PaginatedArticles:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Article"
        pagination:
          type: object
          properties:
            page:
              type: integer
            per_page:
              type: integer
            total:
              type: integer
            total_pages:
              type: integer

Cursor-Based Pagination

Best for real-time data and large datasets:

/events:
  get:
    parameters:
      - name: cursor
        in: query
        schema:
          type: string
        description: Opaque cursor from previous response
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
    responses:
      "200":
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: "#/components/schemas/Event"
                next_cursor:
                  type: string
                  nullable: true
                  description: null when no more results
                has_more:
                  type: boolean

Reusable Pagination Schema

Define pagination once and reuse:

components:
  schemas:
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer

Choosing a Pattern

• Offset/limit: Simple, allows jumping to any page, but slow for large offsets
• Page-based: User-friendly, maps well to UI page numbers
• Cursor-based: Most performant, no missed/duplicate items, but no random page access