OpenAPI: カーソルベースページネーション

APIエンドポイントのカーソルベースページネーションをOpenAPI 3.0で文書化。カーソルパラメータ、ページサイズ制限、next/previousカーソル付きレスポンスメタデータ、hasMoreフラグを解説。

Pagination

詳細な説明

OpenAPIでのカーソルベースページネーションの文書化

カーソルベースページネーションは、データの挿入や削除時も安定したページネーションを提供します。大量データAPIの推奨アプローチです(Twitter、Stripe、Slack、GitHubが使用)。

クエリパラメータ

parameters:
  - name: cursor
    in: query
    schema:
      type: string
    description: Opaque cursor from the previous response's nextCursor field
  - name: limit
    in: query
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 20
    description: Number of items per page (max 100)

ページネーション付きレスポンススキーマ

components:
  schemas:
    PaginatedUsers:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          type: object
          required:
            - hasMore
          properties:
            nextCursor:
              type: string
              description: Cursor for fetching the next page
            previousCursor:
              type: string
              description: Cursor for fetching the previous page
            hasMore:
              type: boolean
              description: Whether more results exist
            totalCount:
              type: integer
              description: Total number of items (optional, may be expensive)

カーソルの仕組み

カーソルは通常、Base64エンコードされた識別子(最後の項目のIDやタイムスタンプ)です。クライアントはあるレスポンスのカーソルを次のリクエストに渡します。このアプローチは、従来のオフセットページネーションで大きなデータセットで遅くなる「オフセットスキップ」問題を回避します。

オフセットページネーションとの比較

機能 カーソル オフセット
大規模データセットでのパフォーマンス 一定 低下
データ変更時の安定性 あり なし(項目がずれる)
任意のページへのジャンプ 不可 可能
実装の複雑さ 高い 低い

カーソルページネーションはフィード、アクティビティログ、頻繁に変更されるデータセットに適しています。オフセットページネーションは小さく静的なデータセットに適しています。

ユースケース

ソーシャルメディアフィード、アクティビティストリーム、取引履歴など、安定した高性能ページネーションが重要な大規模で頻繁に更新されるコレクションを返すAPIエンドポイントの設計に使用。

試してみる — API Documentation Generator

フルツールを開く