はじめに
REST APIやGraphQLなどを設計するとき、「一覧を返すエンドポイント」 は多くのシステムで一般的に実装されます。
しかし、単に「便利だから」「とりあえず用意しておこう」と安易に作ると、思わぬ事故やパフォーマンス問題を引き起こすことがあります。
特に、膨大な件数を一度に返すような実装は、OOM（Out Of Memory）を招き、サービス全体に影響を与える危険があります。
本記事では、一覧エンドポイントを設計する際に本当に必要な視点について解説します。
limitをつければ解決？ ― それだけでは足りない理由
よくある対策は以下です：
- クエリパラメータで
limitを付ける - デフォルトで一定件数（例：100件）だけ返す
もちろんこれは最低限の安全策ですが、これだけでは十分ではありません。
なぜなら、APIを利用するユースケース次第で「どういう一覧が必要か」は大きく変わるからです。
真因は「ユースケース」にある
一覧エンドポイントをどう設計すべきかは、ユースケースを丁寧に洗い出すことから始まります。
例: ユースケース別の設計方針
-
単純に全部のデータを見たい
→ ページング処理（limit+offsetなど）が必要 -
最新のデータだけを扱いたい
→ 日付ベースのフィルタリング（例：from/toパラメータ）や「本日分のみ返す」などの制約で十分 -
一括処理用に利用する
→ バッチ処理に耐えうる設計（ストリーミングや非同期処理）が必要
このように、使い方次第で求められるAPIの姿はまったく異なります。
「とりあえずページングを入れておけばよい」という考え方は危険です。
よくある失敗パターン
-
UI都合で実装を決める
→ とりあえず一覧表示があるからAPIも一覧を返そう、という安易な発想。
→ FE都合だけでなく、BEの観点もしっかり考えて議論が必要。そうしないと、不要に重いレスポンスが発生し、パフォーマンス劣化につながる。 -
全件返却が前提
→ データ量が増えるとすぐにスケールせず、OOMやレスポンス遅延の原因になる。
→ そもそもユースケースを考えていないと件数制限を忘れがちで、最悪はサービス全体の障害につながる。 -
利用シナリオを無視
→ 本来は「最新100件だけで十分」なのに、無駄に複雑なページングAPIを作ってしまう。
→ 結果として開発コストの無駄遣いになり、利用者にとっても不要に複雑なAPIとなってしまう。
補足: 事故の表面的な原因と真因
この手の事故が起きた場合、表面的な原因は limit をつけていなかったことになりますが、
その真因は「ユースケースをちゃんと洗い出せていなかったこと」にあることが多いので、
しっかり原因の深堀りをすることをおすすめします。
コード実装より先に考えるべきこと
エンジニアは「とりあえずコードを書いてみる」方向に進みがちです。
しかし、一覧エンドポイントに関しては、安易にコードを書いて実装する前に、まずユースケースを深く考えることが最重要です。
対策方法はユースケース次第で大きく異なります。
だからこそ、実装に入る前に「このAPIを誰がどう使うのか」を明確にしなければなりません。
時には「すぐに手を動かさない」という勇気を持つことが、事故を防ぐだけでなく、結果的により良いAPI設計につながります。
まとめ
- 一覧エンドポイントは「よくあるから作る」のではなく、ユースケースに基づいて設計することが重要。
-
limitやページングはあくまで表面的な対策にすぎない。 - データ量が増えたときに事故を防ぐためには、利用シナリオを明確にしたうえで設計することが必須。
「とりあえず作る」ではなく、「なぜ必要か」を考えてから作る。
これが、安全で使いやすいAPI設計 ― いや、システム全般の設計の第一歩です。