タイトル: API
SEOタイトル: API とは — Web 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 仕様記述の標準