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エンドポイントの設計に使用。