理Kotowary

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

大人こども
初級中級上級

概要 — まず全体をつかむ

フロント（顔）とバックエンド（頭脳）は、どうやって会話するのか。その窓口の約束がAPIです。

詳細 — 1段階ずつ追う

これは何をする係？

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

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

登場人物メモ:

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

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. フロントが「この形でください」とAPIにお願いする（※3 メソッド＋宛先）
  2. バックエンドが受け取り、認証・認可を確認して処理する
  3. 結果を決まった形（JSON）にまとめて返す
  4. フロントはその形を前提に、画面へはめ込む

登場人物メモ:

  • ※3 メソッド — お願いの種類（取得＝GET、送信＝POST など）
この部分をもっと深く（中級）
  1. クライアントが メソッド＋パス＋ヘッダ（＋ボディ） でリクエスト
  2. バックが認証・認可を確認し、業務ロジックを実行
  3. ステータスコード＋JSON で返す
  4. クライアントは契約（スキーマ）どおりの形を前提に処理

なぜ「決まった形」にする？

  • 壊れにくい — 窓口の形さえ守れば、フロントもバックも別々に作り替えられる
  • 使い回せる — Webのフロントでも、スマホアプリでも、同じAPIを呼べる
  • 分業できる — 「窓口はこの形」と決めれば、フロント担当とバック担当が並行して作れる
この部分をもっと深く（中級）
  • バージョニング — 公開後は破壊的変更を避ける。/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 は相手（サーバ側）の障害。まず族で切り分ける

⚠️ うまくいかないとき

  • 形が違う（400） — お願いの形が約束と違う
  • 本人確認できない（401）／権限なし（403） — 認証・認可で止められた
  • 宛先が無い（404） — そのエンドポイントが存在しない
この部分をもっと深く（中級）
  • 破壊的変更 — 項目名変更・削除で、依存するクライアントが壊れる
  • 過不足の取得（over／under-fetching） — RESTで余分に取る／足りず何度も呼ぶ
  • N+1（GraphQL） — 柔軟な問い合わせがDBクエリを乱発させる

理解度チェック

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

問1. APIが「決まった形」であることの利点に最も近いのは？

問2. APIを一言でいうと？

問3. APIのやり取りに使う「決まった形のデータ表現」に当たるのはどれ？

問4. 「本人確認ができない」ときに返るコードに近いのはどれ？

問5. 本文が挙げる「決まった形にする利点」に当たるのはどれ？

問6. 「そのエンドポイントが存在しない」ときに返るコードはどれ？

問7. 「取得」のお願いに使うHTTPメソッドを英字で答えてください。

問8. APIのお願いの宛先（「この用件はここへ」）を指す片仮名の用語を答えてください。