この記事の要点

API（Application Programming Interface）はソフトウェア同士が機能を呼び出すための取り決め Web API: HTTP 経由で呼ぶ API。スタイルは REST（リソース指向）/ GraphQL（クエリ言語）/ gRPC（高速 RPC）/ WebSocket（双方向） HTTP メソッド: GET（取得）/ POST（作成）/ PUT（更新・置換）/ PATCH（部分更新）/ DELETE（削除） 認証方式: API キー（簡易）/ Bearer トークン（OAuth 2.0、JWT）/ Basic 認証（HTTPS 必須） OpenAPI / Swagger で仕様を記述・公開。API ゲートウェイ（AWS API Gateway、Kong）で認証・Rate Limit を統一

API とは

API（Application Programming Interface）は、ソフトウェアの機能やデータを外部から呼び出すためのインターフェースです。「人間が触る UI」と対になる「プログラムから触る I」と理解できます。

API には大きく分けて 2 種類:

• ライブラリ API: プログラム内で関数 / クラスを呼ぶ（jQuery、React、Pandas など）
• Web API: HTTP 経由で別マシンの機能を呼ぶ（Twitter API、Google Maps API など）

現代のクラウド・SaaS 時代では「API」というと Web API を指すことがほとんどです。本記事も主に Web API を扱います。

Web API のスタイル比較

スタイル	プロトコル	特徴	用途
REST	HTTP + JSON	リソース指向、URL = リソース、メソッド = 操作	Web サービス全般、公開 API の定番
GraphQL	HTTP + JSON	クライアントが必要なフィールドだけ要求	複雑なデータ、モバイル、Facebook、Shopify
gRPC	HTTP/2 + Protobuf	高速・型付き、ストリーミング対応	マイクロサービス間通信、Google
WebSocket	WS (TCP 上)	双方向・常時接続	チャット、リアルタイム配信
SOAP	HTTP + XML	厳格な仕様、レガシー	銀行・政府の古いシステム
SSE	HTTP	サーバー→クライアント単方向のストリーム	通知、ChatGPT のストリーミング

HTTP メソッドと冪等性

メソッド	意味	冪等性	安全性
GET	取得	○（何回呼んでも同じ）	○（副作用なし）
POST	作成・任意操作	×	×
PUT	更新・置換	○	×
PATCH	部分更新	○ または ×（実装依存）	×
DELETE	削除	○（2 回目以降は 404 でも OK）	×
HEAD	ヘッダのみ取得	○	○
OPTIONS	サポートメソッド確認、CORS preflight	○	○

RESTful API の例

# ユーザー一覧取得
GET /api/users HTTP/1.1
Host: api.example.com
Accept: application/json

# 特定ユーザー取得
GET /api/users/123

# ユーザー作成
POST /api/users
Content-Type: application/json

{"name": "Alice", "email": "alice@example.com"}

# ユーザー更新
PUT /api/users/123
Content-Type: application/json

{"name": "Alice Updated", "email": "alice@example.com"}

# 部分更新
PATCH /api/users/123
{"name": "Alice Partial"}

# 削除
DELETE /api/users/123

HTTP ステータスコード

コード	意味	API での使い方
200 OK	成功	GET / PUT / PATCH の成功
201 Created	作成成功	POST でリソース作成、Location ヘッダで URL 返す
204 No Content	成功・ボディなし	DELETE 成功
400 Bad Request	リクエスト不正	バリデーションエラー
401 Unauthorized	認証必要	未ログイン、トークン無効
403 Forbidden	権限なし	ログイン済だが権限不足
404 Not Found	存在しない	リソースなし
409 Conflict	競合	重複登録
422 Unprocessable Entity	意味的エラー	バリデーション NG（Laravel 標準）
429 Too Many Requests	レート制限超過	Rate Limit 違反
500 Internal Server Error	サーバーエラー	サーバーバグ
503 Service Unavailable	停止中	メンテナンス中

認証方式

# 1. API キー（クエリ or ヘッダ）
GET /api/data?api_key=abc123
GET /api/data
X-API-Key: abc123

# 2. Basic 認証（user:password を Base64）
GET /api/data
Authorization: Basic dXNlcjpwYXNz

# 3. Bearer トークン（OAuth 2.0、JWT 等）
GET /api/data
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# 4. HMAC 署名（AWS S3 等）
GET /api/data
Authorization: AWS4-HMAC-SHA256 Credential=...

OAuth 2.0 と JWT

• OAuth 2.0: サードパーティアプリに権限を委譲する仕組み。「Google でログイン」「GitHub でログイン」の裏側で使われる
• JWT (JSON Web Token): 自己完結型のトークン形式。ヘッダ + ペイロード + 署名を Base64URL でつなげた文字列。サーバー側でセッションを持たずに認証可能

JWT の構造（3 つの Base64URL を . で連結）:

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjMiLCJuYW1lIjoiQWxpY2UifQ.SflKxwRJSMeKKF2QT...
  ↑                  ↑                                       ↑
  Header             Payload                                  Signature
  {"alg":"HS256"}    {"sub":"123","name":"Alice","exp":...}   (改ざん検知)

OpenAPI / Swagger

API の仕様を YAML / JSON で記述する標準。ドキュメント生成、SDK 自動生成、モックサーバー生成、テスト自動化に活用:

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0

paths:
  /users/{id}:
    get:
      summary: ユーザー取得
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Not Found

components:
  schemas:
    User:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        email: { type: string, format: email }

クライアントから呼ぶ

# curl
curl https://api.example.com/users/1
curl -H "Authorization: Bearer TOKEN" https://api.example.com/users/1
curl -X POST -H "Content-Type: application/json" \
     -d '{"name":"Alice"}' \
     https://api.example.com/users

# JavaScript (fetch)
const res = await fetch('https://api.example.com/users/1', {
    headers: { 'Authorization': 'Bearer ' + token }
});
const user = await res.json();

# Python (requests)
import requests
r = requests.get('https://api.example.com/users/1',
                 headers={'Authorization': f'Bearer {token}'})
data = r.json()

# PHP (Guzzle)
$client = new GuzzleHttp\Client();
$response = $client->get('https://api.example.com/users/1', [
    'headers' => ['Authorization' => 'Bearer ' . $token]
]);
$data = json_decode($response->getBody(), true);

API ゲートウェイと Rate Limiting

API ゲートウェイは複数のバックエンド API の前段に置く中継サーバー。共通機能を集約:

• 認証 / 認可: トークン検証を一箇所で
• Rate Limiting: 「1 分間に 60 リクエストまで」等の制限
• ルーティング: パスに応じて適切なマイクロサービスへ
• ロギング・モニタリング: 全 API 呼出の記録
• キャッシング: 同じ GET を短時間で複数回呼ばれた場合に高速化
• CORS: クロスオリジン制御

代表的なゲートウェイ: AWS API Gateway / Azure API Management / Kong / Apigee / Tyk / Nginx Plus。

レスポンスヘッダの例（Rate Limit）

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1716123456
Retry-After: 30

FAQ

Q: REST と GraphQL どちらを選ぶ？
A: シンプルな CRUD と公開 APIなら REST。クライアントごとに必要なデータが大きく異なる場合（モバイル、ダッシュボード）は GraphQL が有利。両者は対立ではなく使い分け。

Q: API キーと OAuth どちらを使う？
A: 自社内・サーバー間連携ならAPI キーで十分。第三者アプリにユーザー権限を委譲するならOAuth 2.0。エンドユーザー認証は OpenID Connect（OAuth の拡張）。

Q: バージョニングはどうする？
A: URL パス（/v1/users）が最も一般的。他に Accept ヘッダ（Accept: application/vnd.api.v2+json）方式もあるがハードルが高い。

Q: Rate Limit に当たったときの対処は？
A: レスポンスの Retry-After ヘッダ秒数だけ待ってリトライ。指数バックオフ（1s、2s、4s、8s...）+ ランダムジッターで実装するのが定石。