APIとは — Webサービスをつなぐしくみ（REST・エンドポイント・認証）

API（Application Programming Interface）は、あるソフトウェアの機能を外部のプログラムから呼び出すための取り決めです。中でも HTTP でネットワーク越しに呼び出す Web API は、地図・決済・天気・生成AIなど、あらゆるサービス連携の土台になっています。本記事では、エンドポイントと HTTP メソッド、リクエスト／レスポンスの中身、REST の考え方、認証・認可、そして CORS やレート制限といった実際のつまずきまでを整理します。

1. API とは — 「使い方の取り決め」

API は、機能を提供する側が「この形式で呼べば、この形式で返します」と約束した窓口の仕様です。レストランのメニューに例えられます。客（呼び出す側）は厨房の作り方を知らなくても、メニューに書かれた名前で注文すれば料理が出てきます。内部の実装を知らなくても使えるという点が API の本質です。

• API：広い意味の言葉。OS のシステムコールも、ライブラリの関数も API です。
• Web API：そのうち HTTP を使ってネットワーク越しに呼ぶもの。今日「API を叩く」と言えばほぼこれを指します。
• 提供側は内部実装を自由に作り替えられます。約束（インターフェース）さえ変わらなければ、呼び出す側は影響を受けません。

この「約束」を守ることが提供側の責任であり、だからこそ API にはバージョン（/v1/ など）が付きます。約束を壊す変更（破壊的変更）をするときは、新しいバージョンとして分けるのが定石です。

2. エンドポイントと HTTP メソッド

Web API の呼び出し先 URL をエンドポイントと呼びます。エンドポイントは「どのリソース（対象）か」を表し、HTTP メソッドが「そのリソースに何をするか」を表します。

例：https://api.example.com/v1/users/42 は「ID が 42 のユーザー」というリソースを指します。

べき等（idempotent）とは「同じリクエストを何度送っても、結果の状態が変わらない」性質のことです。通信エラー時に安全に再送できるかを左右するため、実務では重要な区別になります。POST はべき等でないため、決済のような処理では冪等キー（Idempotency-Key ヘッダ等）を付けて二重実行を防ぐ設計がよく使われます。

取得条件はクエリ文字列で渡します。例：GET /v1/users?role=admin&limit=20。値に日本語や記号を含む場合はURLエンコードが必要です。

3. リクエストとレスポンスの中身

HTTP のやり取りは、ヘッダ（メタ情報）とボディ（データ本体）に分かれます。Web API ではボディに JSON を使うのが一般的です。

POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
Accept: application/json

{"name": "田中太郎", "role": "admin"}

これに対する応答は、ステータスコードとヘッダ、そして JSON のボディで返ります。

HTTP/1.1 201 Created
Content-Type: application/json

{"id": 42, "name": "田中太郎", "role": "admin"}

ステータスコードは「どうなったか」を 3 桁で表す、API 読解の要です。

4. REST の考え方 — リソース指向とステートレス

REST（Representational State Transfer）は、Roy Fielding が 2000 年の博士論文で示したアーキテクチャスタイルです。プロトコルでも規格でもなく「Web らしく作るための原則」であり、その原則に沿った API を RESTful な API と呼びます。

• リソース指向：URL は名詞（対象）にし、動作は HTTP メソッドで表します。/v1/users/42 に DELETE であって、/v1/deleteUser?id=42 ではありません。
• ステートレス：サーバはリクエスト間の文脈を保持しません。1 回のリクエストに必要な情報（認証トークンなど）を毎回すべて含めるため、サーバを増やして負荷分散しやすくなります。
• 統一インターフェース：同じ規則（メソッド・ステータスコード・表現形式）を使い回すので、新しい API でも読み方を推測できます。
• キャッシュ可能：GET は安全なので、HTTP のキャッシュ機構をそのまま活かせます。

REST の利点は、HTTP の既存の仕組み（メソッド・ステータスコード・キャッシュ）をそのまま使えることです。学習コストが低く、ツールやプロキシ、CDN との相性も良いため、Web API の事実上の標準になっています。

5. 認証と認可 — APIキー・Bearerトークン・OAuth

公開データ以外の API では、「誰として呼んでいるか」を示す必要があります。認証（誰か）と認可（何をしてよいか）は別の概念です。

• API キー：発行された文字列をヘッダに載せます。単純ですが、キー＝そのまま権限なので秘匿が命です。
• Bearer トークン：Authorization: Bearer <token> の形式（RFC 6750）。「この券を持つ者（bearer）を通す」という意味で、中身に JWT を使うことが多いです。有効期限があるのが利点です。
• OAuth 2.0：ユーザーのパスワードを渡さずに、第三者アプリへ限定的な権限を委譲するための認可フレームワーク（RFC 6749）。「Googleでログイン」の裏側で使われます。

6. つまずきやすい点 — CORS・レート制限・エラー処理

API を実際に呼び始めると、ほぼ必ず出会う 3 つの壁があります。

CORS（クロスオリジン制約）

ブラウザは、あるサイトの JavaScript が別オリジン（ドメイン・スキーム・ポートの組）の API を無制限に読むことを既定で禁じています。許可するには、API 側が Access-Control-Allow-Origin ヘッダを返す必要があります。ここで重要なのは、CORS はブラウザが課す制約であって、サーバ同士の通信や curl には関係しないという点です。「curl では動くのにブラウザだと失敗する」なら、まず CORS を疑います。

レート制限

多くの API は「1 分あたり N 回まで」といった上限を設け、超えると 429 Too Many Requests を返します。Retry-After ヘッダや残回数ヘッダが返ることが多いので、それに従って待ちます。再試行は指数バックオフ（1秒、2秒、4秒…と間隔を空ける）にし、闇雲な即時リトライは避けます。

エラー処理とタイムアウト

ネットワーク越しの呼び出しは失敗するのが普通です。ステータスコードを必ず確認し（fetch は 404 や 500 でも例外を投げません）、タイムアウトを設定し、再試行してよいのはべき等な操作だけ、と決めておきます。

const res = await fetch('https://api.example.com/v1/users/42', {
  headers: { 'Authorization': 'Bearer ' + token, 'Accept': 'application/json' }
});
if (!res.ok) throw new Error('API error: ' + res.status);
const user = await res.json();

7. REST 以外の選択肢 — GraphQL・gRPC・WebSocket

REST が万能というわけではありません。用途に応じて他の方式も使われます。

迷ったら REST から始めるのが定石です。学習コストが低く、ツールが揃っており、必要になったときに他方式へ移行・併用できます。GraphQL は「1画面のために何度も API を呼ぶ（アンダーフェッチ）／使わないフィールドまで返る（オーバーフェッチ）」が痛みとして現れてから検討すれば十分です。