理Kotowary

API — フロントとバックの会話の窓口

大人こども
初級中級上級

概要 — まず全体をつかむ

中級ではRESTと設計の勘所を見ました。上級では、契約・進化・大規模運用へ。

詳細 — 1段階ずつ追う

契約駆動という発想

APIは「先に契約（仕様）を決め、両者がそれに従う」もの。

  • 契約の記述 — OpenAPI（REST）、protobuf（gRPC）、GraphQLスキーマ
  • 契約テスト — 提供側と利用側の食い違いを、テストで自動検出
  • 後方互換 — 追加はOK、削除・意味変更はNG。破るならバージョン
やさしく言うと（中級）

APIにはいくつか流儀があります。Webで最も一般的なのが REST。

  • REST — URL（リソース）＋HTTPメソッドで操作を表す。分かりやすく、キャッシュと相性がよい
  • GraphQL — 必要な項目を、必要な形で1回で取得する（過不足の取得を減らす）
  • RPC/gRPC — 「関数を呼ぶ」感覚。高速で型が厳密
アニメーション『REST API（リソースと動詞）』を開く
REST API — URLで「対象」、動詞で「操作」https://api.example.com/users/123URL＝どのリソースか（対象）を表す。 /users ＝コレクション、/123 ＝その中の1件HTTPの動詞 → 操作（CRUD）対象（同じリソース）性質GET取得（Read）/users/123安全・べき等POST作成（Create）/users/123非べき等PUT更新（Update）/users/123べき等DELETE削除（Delete）/users/123べき等動詞で操作、URLで対象。GET／PUT／DELETE はべき等（何度実行しても結果は同じ）。

登場人物メモ:

  • ※1 エンドポイント／リソース — 操作対象を表すURL（例 /users/1）
  • ※2 契約（スキーマ） — リクエスト／レスポンスの形の取り決め

大規模なやり取り

  1. 検証→認証認可→処理→応答 を、契約に沿って
  2. 冪等キー で再送に耐える
  3. カーソルページング で安定した分割取得
  4. 部分応答・フィールド選択 で過不足を減らす
やさしく言うと（中級）
  1. クライアントが メソッド＋パス＋ヘッダ（＋ボディ） でリクエスト
  2. バックが認証・認可を確認し、業務ロジックを実行
  3. ステータスコード＋JSON で返す
  4. クライアントは契約（スキーマ）どおりの形を前提に処理

形式ごとの勘所

  • REST／GraphQL／gRPC — 汎用・柔軟取得・高速型付き、で使い分け
  • GraphQLのN+1 — DataLoaderでバッチ＋キャッシュ
  • レート制限 — トークンバケット／リーキーバケットで平準化
  • スキーマ進化 — protobufのフィールド番号、GraphQLのdeprecated
  • BFF — 画面ごとに最適な窓口を用意する層
やさしく言うと（中級）
  • バージョニング — 公開後は破壊的変更を避ける。/v2 や項目追加で後方互換を保つ
  • べき等性 — 同じ操作を繰り返しても結果が同じ（GET/PUT/DELETEはべき等、POSTは非べき等）
  • ページング／レート制限 — 大量データは分割、乱用は制限
  • 認証 — トークン（ヘッダ）で本人確認。認可でできる操作を絞る
  • ステータスコードの族 — 2xx＝成功／4xx＝クライアント側の誤り／5xx＝サーバ側の障害。まず族で切り分ける
アニメーション『HTTPステータス（先頭1桁の族）』を開く
HTTPステータス — まず先頭1桁の「族」で読む2xx成功要求どおり処理できた200OK201作成した204中身なし3xxリダイレクト別の場所へ案内・条件付き301恒久的に移動302一時的に移動304未変更4xxクライアント側の誤り要求する側の間違い400不正な要求401未認証403禁止404見つからない5xxサーバ側の誤り応える側の障害500内部エラー502ゲートウェイ不良503利用不可4xx は自分（要求側）の誤り、5xx は相手（サーバ側）の障害。まず族で切り分ける

⚠️ 落とし穴

  • 破壊的変更 — 依存クライアントが壊れる
  • チャッティAPI — 往復が多すぎて遅い（まとめる／BFF）
  • over／under-fetching — RESTで余分／不足
  • バージョン乱立 — v1〜v9が並走し保守不能に
やさしく言うと（中級）
  • 破壊的変更 — 項目名変更・削除で、依存するクライアントが壊れる
  • 過不足の取得（over／under-fetching） — RESTで余分に取る／足りず何度も呼ぶ
  • N+1（GraphQL） — 柔軟な問い合わせがDBクエリを乱発させる

理解度チェック

そのまま解けます（成績は保存されません）。無料アカウントを作ると、学習の記録と進捗の山登りが始まります。

問1. 大量データのページングで、ズレや重複に強いのは？

問2. GraphQLで各フィールドが個別にDBを叩いてしまうN+1を、まとめて解決する定番は？

問3. 後方互換を保つために「やってよい変更」はどれか？

問4. レート制限で流量を平準化する代表的なアルゴリズムはどれか？

問5. BFF（Backend for Frontend）層の役割に最も近いのはどれか？

問6. 「チャッティなAPI」が遅くなりやすい根本原因はどれか？

問7. REST APIの契約（仕様）を機械可読に記述する代表的な仕様の名前を答えてください。

問8. gRPCで契約の記述とデータのシリアライズに使う仕組みを答えてください。