GETリクエストのページネーションパターン

なぜページネーションが必要か？

単一のGETレスポンスで数千レコードを返すのは低速でメモリ集約的です。ページネーションは大規模なコレクションを管理可能なページに分割します。

オフセットベースのページネーション

最もシンプルなアプローチはpageとlimit（またはoffsetとlimit）クエリパラメータを使用します：

GET /api/users?page=3&limit=20 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
X-Total-Count: 542

{
  "data": [ ... 20件のユーザー ... ],
  "meta": {
    "page": 3,
    "limit": 20,
    "totalPages": 28,
    "totalCount": 542
  }
}

利点： シンプル、任意のページへのジャンプをサポート 欠点： 同時挿入/削除との不整合、大きなオフセットで低速（データベーススキャン）

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

ページ番号の代わりに不透明なカーソル（通常base64エンコードされたIDまたはタイムスタンプ）を使用：

GET /api/users?limit=20&after=eyJpZCI6NDB9 HTTP/1.1

HTTP/1.1 200 OK

{
  "data": [ ... 20件のユーザー ... ],
  "cursors": {
    "after": "eyJpZCI6NjB9",
    "before": "eyJpZCI6NDF9",
    "hasNext": true,
    "hasPrevious": true
  }
}

利点： 同時変更があっても一貫性、位置に関わらず高速 欠点： 特定のページにジャンプ不可、クライアントは順次トラバースが必要

Linkヘッダー（RFC 8288）

ページネーションリンクを伝える標準的な方法：

HTTP/1.1 200 OK
Link: </api/users?page=4&limit=20>; rel="next",
      </api/users?page=2&limit=20>; rel="prev",
      </api/users?page=1&limit=20>; rel="first",
      </api/users?page=28&limit=20>; rel="last"

戦略の選択

要素	オフセット	カーソル	キーセット
ページNへジャンプ	可能	不可	不可
一貫した結果	いいえ	はい	はい
スケール時の性能	低速	高速	高速
実装	シンプル	中程度	中程度
最適な用途	小規模データセット、管理UI	フィード、タイムライン	大規模ソート済みデータセット

キーセットページネーション

カーソルベースの変種で、実際のカラム値を使用：

GET /api/users?limit=20&created_after=2026-01-15T10:00:00Z&id_after=42 HTTP/1.1

これは効率的なSQLクエリに直接変換されます：

SELECT * FROM users
WHERE (created_at, id) > ('2026-01-15T10:00:00Z', 42)
ORDER BY created_at, id
LIMIT 20