理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 契約（スキーマ） — リクエスト／レスポンスの形の取り決め

仕事の流れ

  1. クライアントが メソッド＋パス＋ヘッダ（＋ボディ） でリクエスト
  2. バックが認証・認可を確認し、業務ロジックを実行
  3. ステータスコード＋JSON で返す
  4. クライアントは契約（スキーマ）どおりの形を前提に処理

設計の勘所

  • バージョニング — 公開後は破壊的変更を避ける。/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 は相手（サーバ側）の障害。まず族で切り分ける

⚠️ うまくいかないとき

  • 破壊的変更 — 項目名変更・削除で、依存するクライアントが壊れる
  • 過不足の取得（over／under-fetching） — RESTで余分に取る／足りず何度も呼ぶ
  • N+1（GraphQL） — 柔軟な問い合わせがDBクエリを乱発させる

理解度チェック

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

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

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

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

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

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

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

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

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