この記事の要点

API (Application Programming Interface) はソフトウェア同士が通信するための窓口・規約 Web API の主要方式: REST / GraphQL / gRPC / WebSocket / SOAP HTTP メソッド (GET/POST/PUT/PATCH/DELETE) とステータスコード (2xx 成功 / 4xx クライアント / 5xx サーバ) が基本 認証は API キー < OAuth 2.0 < JWT < HMAC 署名 の順で堅牢化 ドキュメンテーションは OpenAPI (Swagger) が事実上の標準、テストには Postman 本番運用に必須: Rate Limiting / API ゲートウェイ / バージョニング

API とは何か

API (Application Programming Interface) は、ソフトウェアやサービスが他のプログラムから利用されるための「窓口」と「規約」をまとめた仕組みです。「決められた呼び出し方をすれば、決められた結果を返す」という契約に基づいています。

身近な例: スマホアプリが天気情報を取得する、決済を行う、地図を表示する、SNS に投稿する。これらはすべて裏側で「サービス提供側の API」を叩いています。

分類	例	用途
Web API	REST / GraphQL / gRPC	ネットワーク越しの通信。本記事の中心
OS API	Win32 API / POSIX	OS 機能の呼び出し（ファイル操作、プロセス等）
ライブラリ API	jQuery / React / NumPy	同一プロセス内の関数呼び出し
ハードウェア API	OpenGL / DirectX / CUDA	GPU・デバイスの抽象化

Web API の主要方式

方式	プロトコル	データ形式	得意領域
REST	HTTP/1.1, HTTP/2	JSON (XML)	汎用 Web API、最も普及
GraphQL	HTTP (POST 主体)	JSON	クライアントが必要な項目だけ取得
gRPC	HTTP/2 (バイナリ)	Protocol Buffers	マイクロサービス間の高速通信
WebSocket	WS / WSS	任意	双方向リアルタイム通信（チャット・株価）
SOAP	HTTP / SMTP	XML	レガシー業務系・金融

HTTP メソッドとステータスコード

REST API の基本は HTTP メソッドとリソース URL の組み合わせです:

メソッド	意味	冪等性	例
GET	取得	○	GET /users/123
POST	作成	×	POST /users
PUT	全体更新	○	PUT /users/123
PATCH	部分更新	×	PATCH /users/123
DELETE	削除	○	DELETE /users/123

ステータスコードは 3 桁で意味が階層化されています:

• 2xx 成功: 200 OK / 201 Created / 204 No Content
• 3xx リダイレクト: 301 Moved Permanently / 304 Not Modified
• 4xx クライアントエラー: 400 Bad Request / 401 Unauthorized / 403 Forbidden / 404 Not Found / 409 Conflict / 422 Unprocessable Entity / 429 Too Many Requests
• 5xx サーバエラー: 500 Internal Server Error / 502 Bad Gateway / 503 Service Unavailable / 504 Gateway Timeout

REST API の呼び出し例

# curl で REST API を呼ぶ
curl -X GET https://api.example.com/v1/users/123 \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Accept: application/json"

# POST でリソース作成
curl -X POST https://api.example.com/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name":"taro","email":"taro@example.com"}'

# PATCH で部分更新
curl -X PATCH https://api.example.com/v1/users/123 \
  -H "Content-Type: application/json" \
  -d '{"email":"new@example.com"}'

GraphQL の例 — 必要な項目だけ取る

# REST だと /users/123 が全項目返す
# GraphQL は欲しい項目だけ指定できる
query {
  user(id: 123) {
    name
    email
    posts(limit: 5) {
      title
      createdAt
    }
  }
}

# レスポンスはクエリと同じ形
{
  "data": {
    "user": {
      "name": "taro",
      "email": "taro@example.com",
      "posts": [...]
    }
  }
}

認証方式 — API キー / OAuth / JWT / HMAC

方式	仕組み	強度	典型用途
API キー	固定文字列をヘッダで送る	低	社内 API / 簡易公開 API
Basic 認証	ID:Pass を Base64	低	HTTPS 前提の管理画面
OAuth 2.0	アクセストークン発行	高	サードパーティ連携（Google / Twitter / GitHub）
JWT	署名付きトークン	高	SPA / モバイル / マイクロサービス
HMAC 署名	リクエスト全体に署名	最高	AWS / 決済 API

OpenAPI / Swagger によるドキュメント

OpenAPI Specification (OAS) は API の仕様を YAML / JSON で記述する標準。Swagger UI でブラウザから試せるドキュメントになります:

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      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}

Rate Limiting と API ゲートウェイ

本番 API には必ず流量制限が必要です。429 Too Many Requests を返し、レスポンスヘッダで残量を伝えます:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 1700000000

# 上限超過時
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{"error": "rate_limit_exceeded", "retry_after": 60}

大規模サービスでは API ゲートウェイ（AWS API Gateway / Kong / Apigee / Tyk）が認証・流量制御・ログ・キャッシュを一括処理します。

バージョニング戦略

• URL に埋める: /v1/users / /v2/users（最も明示的、推奨）
• ヘッダで指定: Accept: application/vnd.example.v2+json
• クエリで指定: ?version=2（非推奨）

FAQ

Q: REST と GraphQL どちらを選ぶ？
A: シンプルな CRUD は REST、画面ごとに取得項目が大きく変わる SPA / モバイルは GraphQL が有利。マイクロサービス内部は gRPC。

Q: API キーと JWT の違いは？
A: API キーは固定文字列で長期間有効、JWT は有効期限付き署名トークンで失効可能。セキュリティは JWT が上。

Q: 公開 API を作るとき最低限やるべきことは？
A: HTTPS 強制 / 認証 / Rate Limit / OpenAPI ドキュメント / バージョニング / エラー形式統一の 6 点。

関連項目

• REST — リソース指向 Web API の設計原則
• GraphQL — Facebook 発のクエリ言語型 API
• OAuth 2.0 / OIDC — 標準的な認可・認証フロー
• OpenAPI / Swagger — API 仕様記述の標準