【テクニカル・上級編】 APIのページネーション設計(Offset-based vs Cursor-based) – Web APIアーキテクチャ・データ連携実践ガイド

ページネーションの深淵：Offset-basedの限界とCursor-basedがもたらすインフラ的恩恵

API設計において、ページネーションは単なる「データの小分け」ではない。それは、データベースのI/O負荷、TCPセッションの生存時間、そしてTLSハンドシェイクのオーバーヘッドが複雑に絡み合う、インフラアーキテクチャの縮図だ。

今日は、多くのAPI設計者が陥る「Offset-based」の罠と、なぜハイパフォーマンスな環境で「Cursor-based」が正義とされるのか、その技術的根拠をカーネルレベルの視点から紐解いていこう。

1. Offset-based Paging：負の連鎖の正体

LIMIT 100 OFFSET 1000000

このクエリを叩いた瞬間、データベースエンジンは裏で何をしているか。100万行をスキャンし、結果セットの100万1行目から100行だけを抽出するために、残りの100万行を捨てている。これは単なるCPUの無駄遣いではない。ディスクI/Oを飽和させ、結果として TCP のレスポンスを遅延させる。

インフラ側の視点で見ると、この「重いクエリ」は、HTTP リクエストに対するサーバーの応答時間を劇的に悪化させる。結果、クライアント側のTCPスタックでは再送タイマーが過敏に反応し、不要な SYN 再送や輻輳制御アルゴリズムのバックオフを誘発する。APIのレスポンスが1秒遅れるだけで、エンドユーザーの体験だけでなく、バックエンドのTCPキューが溢れ、ListenBacklog が枯渇するリスクすらあるのだ。

2. Cursor-based Paging：インフラを救う「ポインタ」の力

Cursor-based（キーセットページネーション）は、特定のユニークなキー（多くの場合 id や created_at）を基準に、検索範囲を限定する。

-- 効率的なCursor-basedの例
SELECT * FROM logs 
WHERE id > :last_seen_id 
ORDER BY id ASC 
LIMIT 100;

このクエリなら、B-tree インデックスを直接参照できるため、スキャン数は LIMIT 分の100行で済む。これはデータベース層でのI/O効率が桁違いであり、結果として TCPセグメント がアプリケーションからネットワークカードへ送り出されるまでの時間が最小化される。

なぜこれがインフラ的に「美しい」のか

1. CPU/Memoryの解放: 巨大な結果セットを一時メモリにロードする必要がない。
2. TLSハンドシェイクとの相性: レスポンスが高速に返るため、TLS 1.3 の 0-RTT 接続を維持したまま、複数のページを短時間でフェッチできる。
3. バッファ効率: TCP Window Size の枯渇を防ぎ、ネットワークのパイプラインを常にクリーンに保てる。

3. 高度な最適化：プロトコルとOSのチューニング

APIの設計が適切であっても、OSやネットワークスタックのチューニングを怠ってはならない。大規模なデータ転送を伴うAPIでは、以下の設定が効いてくる。

TCPバッファの最適化 (sysctl)

大量のレコードを連続して読み込む際、カーネルのTCP送受信バッファが小さいと、スループットが頭打ちになる。

# /etc/sysctl.conf への設定例
# TCP送信バッファの最大値を拡張し、高速なデータ転送を支える
net.ipv4.tcp_wmem = 4096 65536 16777216
# TCP受信バッファの最大値を拡張
net.ipv4.tcp_rmem = 4096 87380 16777216

ヘッダー圧縮とHTTP/2・HTTP/3の活用

ページネーションで取得したメタデータ（Link ヘッダーなど）は、HPACK や QPACK によって圧縮される。特に HTTP/3 (QUIC) を採用すれば、パケットロス時のヘッドオブラインブロッキングを防ぎ、不安定なネットワーク環境下でもページングの継続性を担保できる。

4. セキュリティ：ページネーションが招く脆弱性

Cursor-basedの実装において、cursor 値の取り扱いには注意が必要だ。

インジェクション対策: cursor をそのままSQLに埋め込むのは自殺行為だ。Base64でエンコードして隠蔽しても良いが、本質的には PreparedStatement によるバインドが不可欠である。
DoS耐性: OFFSET を用いたクエリは、攻撃者が OFFSET を最大値にするだけでサーバーリソースを枯渇させる「リソース消費型攻撃」の標的になりやすい。Cursor-basedは、検索範囲が常に WHERE 句で固定されるため、この種の攻撃に対して自然と耐性を持つ。

結論：アーキテクトが目指すべき地平

APIのページネーション設計は、単なる機能要件の充足ではない。データベースのインデックス構成、トランスポート層の輻輳制御、そしてTLSハンドシェイクの効率に至るまでを総合的に設計する「システムインフラの調律」である。

「なぜこのエンドポイントはこれほどまでにレスポンスが速いのか？」
そう現場でエンジニアに問われたとき、胸を張って「TCPスタックの振る舞いとDBのI/Oパスを最適化した結果だ」と答えられるよう、我々は日々プロトコルの深淵を覗き続ける必要があるのだ。

次に設計するAPIでは、ぜひ OFFSET ではなく Cursor を選んでみてほしい。パケットがより軽やかに、かつ安全にネットワークを駆け巡るはずだ。