📑 この章の目次
- title: API & エンドポイント icon: 🔌 card_desc: プログラム同士が通信する窓口の約束事 — HTTP基礎・ステータスコード・REST・GraphQL・WebHook slug: 03-api-endpoint
- 一言でいうと
- 1. なぜAPIという「約束事」が必要なのか
- 2. HTTP —— Web APIの共通語
- 3. 🔑 ステータスコード —— 「結果はどうだったか」
- 4. REST —— 「URLとHTTPメソッドで機能を表現する」設計思想
- 5. WebHook —— 「サーバーがクライアントに通知する」仕組み
- 6. API設計でよくある失敗と対処
- 7. 面接・実務での意味
- まとめ
title: API & エンドポイント icon: 🔌 card_desc: プログラム同士が通信する窓口の約束事 — HTTP基礎・ステータスコード・REST・GraphQL・WebHook slug: 03-api-endpoint
03 API & エンドポイント — プログラム同士が通信する「窓口」の約束事
「API」「エンドポイント」「REST」、そして「200・404・500」——現場の会話で当たり前のように出るこれらの言葉、何を指しているか正確に言えますか？ この章では、プログラム同士がやり取りするための約束事を根本から理解します。
一言でいうと
API（Application Programming Interface） は、プログラム同士が会話するときの約束事（インターフェース）です。「こういう形式で聞けば、こういう形式で答えます」という取り決めです。エンドポイント（endpoint） は、その窓口（住所）。「/users/123 というURLに聞けば、ユーザー情報が返ってくる」のように、URLで機能を識別します。
1. なぜAPIという「約束事」が必要なのか
たとえば、天気予報サービスを作りたいとします。自前で観測装置を持ち、気象データを解析し、地図上に表示する——これは現実的ではありません。
そこで登場するのがAPIです。
あなたのアプリ ──→ 気象会社のAPI（=約束事）
「/weather?city=Tokyo に GET で聞くとJSONが返る」
あなたのアプリ ←── { "temp": 22, "weather": "晴れ" }
APIのおかげで、あなたは気象学の知識ゼロで天気予報アプリを作れます。**「誰かが用意した機能を、自分のアプリから呼び出す」**のがAPIです。
💡 「インターフェース」＝ 接点・境界。人間同士が言葉を介して話すように、プログラム同士がAPIという共通の言葉で話します。
2. HTTP —— Web APIの共通語
現在、APIの事実上の標準は HTTP（HyperText Transfer Protocol） です。Web ブラウザが Web ページを取得するときに使うのと同じ仕組みが、プログラム間の通信にも使われます。
リクエストとレスポンス
HTTP のやりとりは、**「リクエスト（お願い）」と「レスポンス（お返事）」**の2つで成り立ちます。
[クライアント] [サーバー]
│ │
│ ── GET /weather?city=Tokyo ───────> │ ← リクエスト
│ │
│ <── 200 OK { "temp": 22 } ──────── │ ← レスポンス
│ │
メソッド ——「お願い」の種類
HTTP には、**「何をしたいか」**を示すメソッド（動詞）があります：
| メソッド | 意味 | 例え |
|---|---|---|
| GET | 取得したい（ページを見る） | 本棚から本を取り出して読む |
| POST | 新しく作成したい（記事を書く） | 新しく本を出版する |
| PUT | 全体を更新したい（記事をまるごと書き換え） | 本を丸ごと改訂する |
| PATCH | 一部だけ更新したい（記事の一部を修正） | 本の数ページだけ差し替える |
| DELETE | 削除したい | 本を破棄する |
💡 PUT と PATCH の違いは初学者がつまずきやすい所です。PUT は「対象を丸ごと置き換え」、PATCH は「一部だけ変更」。両方とも更新ですが、粒度が違います。
CRUD と HTTPメソッドの対応
| 操作（CRUD） | HTTPメソッド | 例 |
|---|---|---|
| Create（作成） | POST | POST /users |
| Read（読み取り） | GET | GET /users/123 |
| Update（更新） | PUT / PATCH | PUT /users/123、PATCH /users/123 |
| Delete（削除） | DELETE | DELETE /users/123 |
⚠ 「GET で削除できる API」は設計違反。GET は「副作用がない」ことが約束で、ブラウザのキャッシュや履歴が混乱します。CRUD と HTTP メソッドの対応を理解するのが第一歩です。
エンドポイントの完全な形
エンドポイントは完全な URLの中の「パス部分」です。
https://api.weather.com/v1/weather?city=Tokyo
─────── ──────── ────────── ────────
スキーム ドメイン パス クエリ
(https) (api...) ↑ この部分が「エンドポイント」
- ベースURL：
https://api.weather.com/v1（サービス提供者が用意） - エンドポイント：
/weather?city=Tokyo（機能ごとに用意された窓口） - クエリパラメータ：
?city=Tokyo（追加条件）
💡 レスポンスのフォーマット: 上の例 { "temp": 22, "weather": "晴れ" } は JSON（JavaScript Object Notation） と呼ばれる形式です。現在 API の事実上の標準フォーマットで、「キーと値のペア」を {} で囲むだけのシンプルな記法です。
3. 🔑 ステータスコード —— 「結果はどうだったか」
レスポンスには**3桁の数字（ステータスコード）**が必ず含まれます。これは「お返事の結果」を機械的に伝える仕組みです。
主要なステータスコード
| コード | 意味 | ざっくり分類 |
|---|---|---|
| 200 OK | 成功 | ✅ 成功（2xx） |
| 201 Created | 作成成功 | ✅ 成功（2xx） |
| 204 No Content | 成功（返す内容なし） | ✅ 成功（2xx） |
| 301 Moved Permanently | 恒久的に移動した（SEO評価も引き継ぐ） | 🔄 リダイレクト（3xx） |
| 304 Not Modified | キャッシュを使ってよい | 🔄 リダイレクト（3xx） |
| 400 Bad Request | リクエストの形式がおかしい | ❌ クライアントエラー（4xx） |
| 401 Unauthorized | 認証情報が無効または未提供（ログインしてない／期限切れ） | ❌ クライアントエラー（4xx） |
| 403 Forbidden | 認証済みだが権限がない（このリソースを見る権限がない） | ❌ クライアントエラー（4xx） |
| 404 Not Found | 見つからない | ❌ クライアントエラー（4xx） |
| 429 Too Many Requests | リクエスト過多（レート制限） | ❌ クライアントエラー（4xx） |
| 500 Internal Server Error | サーバーの内部エラー | 💥 サーバーエラー（5xx） |
| 502 Bad Gateway | 上流サーバーが応答不能 | 💥 サーバーエラー（5xx） |
| 503 Service Unavailable | サービス停止中（メンテ・過負荷） | 💥 サーバーエラー（5xx） |
コード番号の法則
コードは百の位で大分類できます：
| 範囲 | 意味 | 誰が対処すべきか |
|---|---|---|
| 2xx | 成功 | 問題なし |
| 3xx | リダイレクト（別の場所を見て） | クライアントが自動で追従 |
| 4xx | クライアント側のミス | リクエストを直す |
| 5xx | サーバー側のミス | サーバーを直す（リトライで治ることもある） |
💡 「4xx と 5xx の区別」は面接頻出です。「404 Not Found」は「あなたのURL指定が間違っている（=あなたの責任）」、「500 Internal Server Error」は「サーバー側が悪い（=サーバー提供者の責任）」。コード番号を見ただけで、どこを直すべきか当たりがつくのが理想です。
4. REST —— 「URLとHTTPメソッドで機能を表現する」設計思想
API の設計スタイルとして最も普及しているのが REST（Representational State Transfer） です。
RESTの基本原則
- URLは「リソース（資源）」を表す：
/users/123（ユーザー123）、/posts/456/comments（記事456へのコメント） - HTTPメソッドで「何をするか」を表現：
GET /users/123（取得）、DELETE /users/123（削除） - ステートレス：サーバーはクライアントの状態を記憶しない（セッション・Cookie 自体は使ってよいが、サーバー側で「このクライアントはさっき何をしていたか」を保持しない。各リクエストに必要な情報を全部載せる）
RESTfulなURL設計の例
GET /users ユーザー一覧を取得
GET /users/123 ユーザー123を取得
POST /users 新しいユーザーを作成
PUT /users/123 ユーザー123を更新
DELETE /users/123 ユーザー123を削除
GET /users/123/posts ユーザー123の記事一覧を取得
⚠ 重要: 「名詞」で URL を設計し、「動詞」はメソッドで表現します。/getUser や /deleteUser のような URL は REST らしくありません。GET /users/123 のように、URLは「対象」、メソッドは「操作」を担当させるのが REST の流儀です。
REST ≠ 必須
REST は設計思想であり、唯一の正解ではありません。API 設計スタイルには他にもあります：
| スタイル | 特徴 | 主な用途 |
|---|---|---|
| REST | URL + HTTPメソッド + ステータスコード。リソース中心 | 一般的なWeb API |
| GraphQL | 「欲しいフィールドだけ」を1リクエストで指定。過不足なく取得 | フロントエンド主体・複雑なデータ関係 |
| RPC / gRPC | 「関数呼び出し」風。高速・型付き | マイクロサービス間通信 |
| WebSocket | 双方向・常時接続 | チャット・リアルタイム更新 |
「REST が一番」と覚えず、**「場面に応じて選ぶ」**のがプロの視点です。
5. WebHook —— 「サーバーがクライアントに通知する」仕組み
通常の API はクライアント起点（クライアントがサーバーに聞きに行く）です。しかし「ユーザー登録が完了したら通知がほしい」「決済が完了したら自動で処理したい」のように、サーバーが能動的に教えてくれる仕組みが必要な場合があります。
それが WebHook（ウェブフック） です。
通常のAPI: [あなたのアプリ] ──問合せ──> [決済サービス]
[あなたのアプリ] <─回答──── [決済サービス]
WebHook: [あなたのアプリ] <─通知──── [決済サービス]
（事前に「通知先URL」を登録しておく）
使いどころ
- 決済完了通知（Stripe・PayPal 等）: 決済サービス → あなたのサーバー
- CI 完了通知（GitHub Actions）: GitHub → あなたのサーバー
- フォーム送信通知: フォームサービス → あなたのチャットツール
⚠ 設計の勘所: WebHook は公開エンドポイントになるため、**署名検証（secret による認証）**がほぼ必須です。さもなければ、攻撃者が偽の通知を送れてしまいます。
6. API設計でよくある失敗と対処
| 失敗 | 何が起きるか | 対処 |
|---|---|---|
| エラーを一律 200 で返す | クライアントが失敗を検知できない | 失敗時は必ず意味のある 4xx/5xx を返す |
| エラーメッセージが曖昧 | 「エラーが発生しました」だけだと直せない | 構造化エラー（{ "code": "INVALID_EMAIL", "message": "...", "field": "email" }）で機械的に処理可能にする |
| バージョンを変えない | クライアントが壊れる恐怖で変更できない | URL か ヘッダで API バージョン を明示（/v1/users 等） |
| 認証・認可が甘すぎる | 不正アクセス・データ漏洩 | 認証必須・権限チェック・HTTPS 強制（→ 第4章・第5章） |
| レート制限がない | 大量アクセスでサーバーが落ちる | リクエスト数の上限を設定（429 で返す） |
7. 面接・実務での意味
「API 設計で気をつけることは？」
この質問は、単に「REST 知っていますか」を聞いているのではありません。**「相手と約束事を交わせるか・想定外の利用に耐えられるか・壊れた時に何が悪いか即座に判定できるか」**を聞いています。
- ステータスコードを適切に返しているか
- URLがリソース指向か
- エラーの形式が構造化されているか
- 認証・認可が漏れていないか
- バージョニングの方針があるか
これらを自覚して設計できることが、「API を使える」ではなく「API を設計できる」エンジニアの証です。
まとめ
- API はプログラム間の約束事。エンドポイントは窓口（URL）
- HTTP は事実上の標準。GET/POST/PUT/DELETE で操作を伝える
- ステータスコードで結果を機械的に判定。2xx=成功・4xx=クライアント側の問題・5xx=サーバー側の問題
- REST は URL（名詞）+ メソッド（動詞）で機能を表現する設計思想。唯一の正解ではない
- WebHook は「サーバーから能動的に通知する」仕組み。署名検証必須
- API 設計の品質は、エラー処理・バージョニング・認証・レート制限で決まる
💡 次のステップ: API が「プログラム同士の約束事」だと分かると、「APIキーやパスワードはどうやって渡すのか」が気になります。第4章では、認証情報・秘密情報をコードに直接書かない作法（環境変数・シークレット管理）を扱います。