概要
API（Application Programming Interface）は、アプリ間の取り決めです。クライアントは契約（エンドポイント、メソッド、入出力）を履行し、サーバは規約通り応答します。
- HTTPメソッド：GET/POST/PUT/PATCH/DELETE
- 表現形式：JSON（主流）、XML、CSV
- 認証：APIキー、Bearerトークン、OAuth 2.0
- 運用の肝：バージョニング、エラー規約、レート制限、監視、ログ
基本
HTTPの基本
# curl でJSON APIを呼ぶ例
curl -s -H "Accept: application/json" \
"https://jsonplaceholder.typicode.com/todos/1"レスポンス例
{
"userId": 1,
"id": 1,
"title": "delectus aut autem",
"completed": false
}JSONの約束
- フィールド名は
snake_caseまたはcamelCaseに統一 - 時刻は ISO 8601（例:
2025-08-18T03:15:00+09:00） - エラーは
code,message,detailsを基本に
{
"code": "RATE_LIMITED",
"message": "Too many requests",
"details": {"retry_after": 3}
}基礎
RESTを前提に、コレクションと単一リソースを分けます。
GET /v1/articles # 一覧
POST /v1/articles # 作成
GET /v1/articles/{id} # 取得
PATCH /v1/articles/{id} # 部分更新
DELETE /v1/articles/{id} # 削除共通ヘッダ：
Authorization: Bearer <ACCESS_TOKEN>
X-Request-Id: 9b2a... # 分散トレース用導入
クライアント（Fetch）
async function fetchTodo(id=1) {
const res = await fetch(`https://jsonplaceholder.typicode.com/todos/${id}`);
if (!res.ok) throw new Error('HTTP ' + res.status);
return await res.json();
}サーバ（PHP: cURL）
<?php
$ch = curl_init('https://jsonplaceholder.typicode.com/todos/1');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => ['Accept: application/json']
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
http_response_code($code);
header('Content-Type: application/json; charset=utf-8');
echo $body;開発現場
バージョニング
/v1/をURLに含める or ヘッダAccept: application/vnd.myapi+json;version=1。エラー規約
4xxはクライアント、5xxはサーバ。
code/message/detailsで機械可読に。可観測性
ヘルスチェック
/healthz、構造化ログ、分散トレースID。秘密情報
キーはサーバ側で管理。フロントに直埋め込みはNG。
よく使われるテクニック
リトライ（指数バックオフ）
async function fetchWithRetry(url,{retries=3,base=300}={}){
for(let i=0;i<=retries;i++){
const res = await fetch(url);
if(res.ok) return res;
const ra = res.headers.get('Retry-After');
const wait = ra ? parseInt(ra,10)*1000 : Math.pow(2,i)*base;
await new Promise(r=>setTimeout(r,wait));
}
throw new Error('Max retries exceeded');
}ページネーション
GET /v1/items?limit=20&cursor=eyJpZCI6MTIzfQ==
X-Next-Cursor: eyJpZCI6MTI0fQ==固定順序・安定ソート（例: ID昇順）＋ cursor を返す。
Idempotency-Key
POST /v1/payments
Idempotency-Key: 74c9...
{ "amount": 1200, "currency": "JPY" }CORS と CSRF
公開APIは CORS 設定、管理画面は CSRFトークン（SameSite=Lax Cookie）。
Excelのフォーマット
API仕様の最小CSV（Excelで開けます）。ボタンでダウンロード可能。
| 名前 | エンドポイント | メソッド | 必須パラメータ | 任意パラメータ | サンプルレスポンス |
|---|---|---|---|---|---|
| Todo取得 | /v1/todos/{id} | GET | id:number | - | {"id":1,"title":"..."} |
| 記事作成 | /v1/articles | POST | title:string | tags:string[] | {"id":101,"title":"..."} |
※ クライアント式CSVはテーブルを変えればそのまま出力。サーバ式は api/download_csv.php を編集。
最新情報
応用
サンプルAPI（PHP）
api/demo.php は簡易RESTの雛形です。
GET /api/demo.php?action=list
GET /api/demo.php?action=detail&id=1
POST /api/demo.php?action=create (JSON本文)
PATCH /api/demo.php?action=update&id=1 (JSON本文)
DELETE /api/demo.php?action=delete&id=1安全なプロキシ
CORSを回避するための api/proxy.php?url=...（許可ホストのみ）。
/api/proxy.php?url=https%3A%2F%2Fjsonplaceholder.typicode.com%2Ftodos%2F1発展
- OpenAPI 3.1 → コード生成（サーバ/SDK/ドキュメント）
- GraphQL・gRPC：用途に応じて選択
- レート制限（トークンバケット）、キャッシュ（ETag/If-None-Match）
- セキュリティヘッダ、WAF、Bot対策
よく使うツール
curl
最強のデバッグCLI。
Postman / Insomnia / Hoppscotch
APIスイート。
Swagger UI / Redoc
OpenAPIの可視化。
jq
JSON整形・抽出。
mitmproxy
HTTP観察。
k6 / Locust
負荷試験。
より具体的に：ブラウザで試せるAPIコンソール
結果
—