API 設計

REST は、URL でリソース（もの）を表し、HTTP メソッドで操作を表す設計のスタイルです。HTTP の決まりに沿うので、キャッシュ・リトライ・監視などの仕組みをそのまま使えます。

URL の命名・ネスト

• 名詞の複数形にし、動詞（/getUser）は入れない。小文字とハイフン、またはチーム内で決めた形に統一する。
• ネストは1段まで（/users/42/orders）。深くすると URL が長くなり、親の ID が無いと使えなくなる。2段以上は /orders?user_id=42 のように絞り込みで表す。
• JSON のキーの形（snake_case か camelCase）、日時（ISO 8601、UTC）もそろえる。

OpenAPI の基本の形（API の仕様書の章）

エラーの本文の形を API 全体でそろえると、クライアントが共通の処理を書けます。RFC 9457（Problem Details）は、その標準の形です。

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://example.com/problems/validation",
  "title": "入力内容に誤りがあります",
  "status": 422,
  "detail": "email の形式が正しくありません",
  "errors": [{ "field": "email", "code": "invalid_format" }]
}

画面に出す文言とは別に、機械が判定できる code を持たせます。500 の詳細（スタックトレース・SQL）は返さず、代わりにログと結びつける ID（リクエスト ID）を返します。

GraphQL の N+1 と、その対策の DataLoader は次のトピックで扱います。

GraphQL は「取りすぎ・足りない」を防げますが、クエリが自由なぶん、重いクエリへの対策（深さや複雑さの上限）、権限の確認をフィールドごとに考える必要があります。gRPC は型が厳密で速いので、マイクロサービスの間でよく使われます。

GraphQL ではフィールドごとに解決する関数（リゾルバー）が呼ばれます。記事 20 件と、それぞれの著者を取るクエリだと、著者のリゾルバーが 20 回呼ばれ、素直に書くと SQL が 1＋20 回になります。

DataLoader は、同じタイミングで呼ばれた「著者 ID で取って」をまとめて、WHERE id IN (…) の1回にする仕組みです。リクエストごとに作り直すことで、他のユーザーとキャッシュが混ざらないようにします。

GraphQL ではあわせて、クエリの深さや複雑さの上限、1回に返す件数の上限を決めて、重いクエリで DB が倒れないようにします。

一覧の API は、件数が増えても速く返せるよう、少しずつ返す（ページング）のが前提です。limit の上限（例：100）も必ず決めます。

カーソルは「最後に返した行の、並び順のキーの値」です。並び順のキーは一意でなければなりません。created_at だけだと同じ時刻の行で抜けや重複が起きるので、id と組み合わせます。

-- 新しい順。前のページの最後が (2026-11-01 10:00, 123)
SELECT * FROM posts
WHERE (created_at, id) < ('2026-11-01 10:00', 123)
ORDER BY created_at DESC, id DESC
LIMIT 21;  -- 1件多く取り、次があるか判定する
-- インデックス：(created_at, id)

この値を JSON にして Base64 で包み、クライアントには中身を気にせず渡すだけの文字列として返します（"next_cursor": "…"）。中身に頼らせないことで、後から並び順の作りを変えられます。改ざんされたカーソルで困る場合は署名を付けます。行の比較 (a, b) < (x, y) が使えない DB では a < x OR (a = x AND b < y) と書きます。

決済・注文・メール送信のような「1回だけ起きてほしい」処理では、やり直しによる二重の実行が、お金や信用に関わる事故になります。同じリクエストが2回届く道は、利用者のボタンの連打、スマホの回線の切れ、クライアントのライブラリやプロキシによる自動のリトライなど、いくつもあります。

冪等性は、リトライを安全にするための API 設計の基本で、面接でも定番の話題です。

通信は失敗します。クライアントがタイムアウトしたとき、サーバーが「処理する前に落ちた」のか「処理は終わったが応答が届かなかった」のかは区別できません。そのため、同じリクエストを何回送っても結果が1回分になる（冪等）ようにしておくと、安全にリトライできます。

メソッドとリトライ

GET・PUT・DELETE はもともと冪等なので、そのままリトライしてかまいません。POST（作成・決済・メール送信）は冪等ではないので、何もしないと二重に作られます。

冪等キーの仕組み

クライアントが操作ごとに一意のキー（UUID）を作り、リトライのときも同じキーを送ります。

POST /payments
Idempotency-Key: 6f1c2e8a-...
{"amount": 1200, "order_id": 77}

• サーバーはキーを一意制約つきの表に保存し、同時に来た2つ目は保存に失敗するので、処理中なら 409 を返す。
• 処理が終わったら、ステータスと応答の本文をキーと一緒に保存する。
• 同じキーがまた来たら、処理をせず保存しておいた応答を返す。
• 同じキーなのに中身が違うリクエストは 422 などで拒否する。キーは 24 時間など期限を決めて消す。

キーの保存と本来の処理（注文の作成）は、同じトランザクションで行うと食い違いません。外部の決済サービスを呼ぶときは、そちらにも冪等キーを渡します（多くの決済 API が対応しています）。

下の「ブラウザで試す」の図では、アプリが冪等キー付きで注文を送り、サーバーが注文とキーを同じトランザクションで保存したあと、返事が途中で消えます。アプリは間をあけて同じキーで送り直し、サーバーは処理済みのキーだと分かるので、注文を作り直さずに前回の結果を返します。上の箇条書きの「同じキーがまた来たら、保存しておいた応答を返す」の手順に注目してください。同時に2つ届いたときの 409 や、中身が違うときの 422 は図には出てきません。

• 間隔は指数バックオフ＋ジッター（1秒・2秒・4秒…にばらつきを足す）。全員が同時にリトライすると、復旧しかけたサーバーを再び倒す。回数にも上限を付ける。
• ジョブのキューも「少なくとも1回」届く前提なので、ワーカー側も冪等に作る。

リトライは、呼ぶ側の全部の層で重ねると回数が掛け算になります（3層 × 3回 ＝ 最大 27回）。リトライはできるだけ1か所（一番外側か、一番内側）にまとめます。

公開した API は、使っている側（スマホのアプリ・他社）がすぐには更新できないので、壊さずに変えるのが基本です。

• 壊さない変更：項目の追加、任意のパラメータの追加、新しいエンドポイント。クライアントは知らない項目を無視するように作る。
• 壊す変更：項目の削除・名前の変更・型の変更、必須パラメータの追加、エラーの形の変更、列挙値の追加（クライアントが想定していないと壊れることがある）。

バージョンの付け方

大きな版（v2）を作るのは最後の手段です。2つの版を同時に保守する手間がかかるので、まずは追加で対応できないか考えます。

• 廃止の予定と移行先を告知し、期限（数か月以上）を決める。
• 応答に Deprecation・Sunset ヘッダーで廃止予定を示す。
• 古い版・古い項目の利用をログで数え、利用者に個別に連絡する。
• アプリの場合は、強制アップデートの仕組みと組み合わせる。
• 利用がほぼなくなってから止める。一時的に止めて反応を見る（短いブラウンアウト）方法もある。

Deprecation: @1767225600
Sunset: Wed, 30 Jun 2027 00:00:00 GMT
Link: <https://example.com/docs/migrate-v2>; rel="deprecation"

Sunset ヘッダーは RFC 8594、Deprecation ヘッダーは RFC 9745 で決められています。値は日付で、移行の手順のページへのリンクも添えると親切です。

公開した API やログイン画面には、正しい利用者だけでなく、パスワードを総当たりするボットや、バグで同じリクエストを連打するクライアントも来ます。何も制限しないと、一部の相手のせいで DB やサーバーが埋まり、全員が使えなくなります。

レート制限はその守りの基本で、API の設計・セキュリティ・障害対応のどれでも出てくる話題です。

レート制限は、1人（またはキー・IP）が一定時間に送れる回数を決めて、超えたら 429 Too Many Requests を返す仕組みです。総当たりのログイン・スクレイピング・バグったクライアントの連打から、サービス全体を守ります。

多くの台数で共有するカウンターは Redis の INCR が原子的なので、数え間違えません。実装は Redis の使い方で試せます。

SRE の「レート制限のアルゴリズム」

下の「ブラウザで試す」の図では、API サーバーが2台ある構成で、1つのリクエストが LB と API を通り、Redis に回数を問い合わせてから 200 か 429 が返るまでを追えます。台ごとに数えると上限が台数倍になること、固定ウィンドウ・スライディングウィンドウ・トークンバケットで Redis に送るコマンド（INCR・ソート済みセット・Lua スクリプト）がどう違うかを、上の図の3つの数え方と見比べてください。429 に付ける Retry-After と残り回数のヘッダー、表の「数える単位」（ログイン前は IP、ログイン後はユーザー ID・API キー）、Redis が落ちたときに通すか止めるかの手順もあります。