OpenAPIでのページネーションパターン

OpenAPIでのページネーション

アイテムのリストを返すすべてのAPIエンドポイントにはページネーションが必要です。OpenAPIはoffset/limit、ページベース、カーソルベースのアプローチを含むすべての主要なページネーションパターンをドキュメント化できます。

Offset/Limitページネーション

最もシンプルなアプローチ：

/items:
  get:
    parameters:
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 100

ページベースページネーション

よりユーザーフレンドリーな番号付け：

/articles:
  get:
    parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        schema:
          type: integer
          default: 25
          maximum: 100

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

リアルタイムデータと大規模データセットに最適：

/events:
  get:
    parameters:
      - name: cursor
        in: query
        schema:
          type: string
        description: 前のレスポンスからの不透明カーソル
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200

パターンの選択

• Offset/limit: シンプル、任意のページにジャンプ可能、大きなオフセットでは遅い
• ページベース: ユーザーフレンドリー、UIのページ番号によくマッピングされる
• カーソルベース: 最も高パフォーマンス、欠落/重複なし、ランダムページアクセスは不可