理Kotowary

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

大人こども
初級中級上級

概要 — まず全体をつかむ

初級ではAPIを「注文票」と捉えました。中級では、代表的な形式 REST を軸に、設計の勘所を見ます。

詳細 — 1段階ずつ追う

これは何をする係？

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 契約（スキーマ） — リクエスト／レスポンスの形の取り決め
この部分をもっと深く（上級）

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

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

レストランの注文票を思い浮かべてください。メニュー（決まった項目）に沿って書けば、決まった料理が返ってくる。お客さん（フロント）と厨房（バック）は、注文票という共通の形を通してやり取りします。

APIも同じ。「この形でお願いすれば、この形で返す」という約束です。

登場人物メモ:

  • ※1 エンドポイント — お願いの宛先（「この用件はここへ」）
  • ※2 JSON — やり取りに使う、決まった形のデータ表現

仕事の流れ

  1. クライアントが メソッド＋パス＋ヘッダ（＋ボディ） でリクエスト
  2. バックが認証・認可を確認し、業務ロジックを実行
  3. ステータスコード＋JSON で返す
  4. クライアントは契約（スキーマ）どおりの形を前提に処理
この部分をもっと深く（上級）
  1. 検証→認証認可→処理→応答 を、契約に沿って
  2. 冪等キー で再送に耐える
  3. カーソルページング で安定した分割取得
  4. 部分応答・フィールド選択 で過不足を減らす
やさしく言うと（初級）
  1. フロントが「この形でください」とAPIにお願いする（※3 メソッド＋宛先）
  2. バックエンドが受け取り、認証・認可を確認して処理する
  3. 結果を決まった形（JSON）にまとめて返す
  4. フロントはその形を前提に、画面へはめ込む

登場人物メモ:

  • ※3 メソッド — お願いの種類（取得＝GET、送信＝POST など）

設計の勘所

  • バージョニング — 公開後は破壊的変更を避ける。/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 は相手（サーバ側）の障害。まず族で切り分ける
この部分をもっと深く（上級）
  • REST／GraphQL／gRPC — 汎用・柔軟取得・高速型付き、で使い分け
  • GraphQLのN+1 — DataLoaderでバッチ＋キャッシュ
  • レート制限 — トークンバケット／リーキーバケットで平準化
  • スキーマ進化 — protobufのフィールド番号、GraphQLのdeprecated
  • BFF — 画面ごとに最適な窓口を用意する層
やさしく言うと（初級）
  • 壊れにくい — 窓口の形さえ守れば、フロントもバックも別々に作り替えられる
  • 使い回せる — Webのフロントでも、スマホアプリでも、同じAPIを呼べる
  • 分業できる — 「窓口はこの形」と決めれば、フロント担当とバック担当が並行して作れる

⚠️ うまくいかないとき

  • 破壊的変更 — 項目名変更・削除で、依存するクライアントが壊れる
  • 過不足の取得（over／under-fetching） — RESTで余分に取る／足りず何度も呼ぶ
  • N+1（GraphQL） — 柔軟な問い合わせがDBクエリを乱発させる
この部分をもっと深く（上級）
  • 破壊的変更 — 依存クライアントが壊れる
  • チャッティAPI — 往復が多すぎて遅い（まとめる／BFF）
  • over／under-fetching — RESTで余分／不足
  • バージョン乱立 — v1〜v9が並走し保守不能に
やさしく言うと（初級）
  • 形が違う（400） — お願いの形が約束と違う
  • 本人確認できない（401）／権限なし（403） — 認証・認可で止められた
  • 宛先が無い（404） — そのエンドポイントが存在しない

理解度チェック

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

問1. 既存APIの返す項目名をいきなり変えると起きやすい問題は？

問2. Webで最も一般的な、URL（リソース）とHTTPメソッドで操作を表すAPIの流儀を答えてください。

問3. 5xx系のステータスコードが表すのは「◯◯側の障害」。◯◯に入る語を答えてください。

問4. RESTで「取得（副作用なし）」に使うHTTPメソッドは？

問5. 同じ操作を繰り返しても結果が変わらない「べき等」とされるのはどれか？

問6. ステータスコードで「クライアント側の誤り」を表す族はどれか？

問7. RESTと比べたGraphQLの主な狙いに最も近いのはどれか？

問8. 「関数を呼ぶ」感覚で高速・型が厳密、という説明に最も近い流儀はどれか？