✍️ 필사 모드: API設計完全ガイド — REST・OpenAPI・Versioning・Pagination・Idempotency・Webhooks 2025年版

Level 0: 単一エンドポイント + POST ですべて
Level 1: リソースごとのURL(まだverbが残る)
Level 2: HTTPメソッドを正しく使う
Level 3: HATEOAS(ハイパーメディア)

Good: /users/123/orders
Bad:  /getUserOrders?userId=123

Good: /users, /orders, /products
Bad:  /user, /order(混在)

200 OK / 201 Created / 202 Accepted / 204 No Content
400 Bad Request / 401 Unauthorized / 403 Forbidden
404 / 409 Conflict / 422 Unprocessable / 429 Too Many Requests
500 / 502 / 503 / 504

{
  "type": "https://example.com/errors/insufficient-funds",
  "title": "Insufficient funds",
  "status": 422,
  "detail": "Account balance $50 is less than required $100",
  "instance": "/accounts/12345/transactions/abc",
  "errors": [
    { "field": "amount", "message": "must be <= balance" }
  ],
  "requestId": "req_abc123"
}

{ "createdAt": "2026-04-15T12:34:56Z" }

{ "amount": 10000, "currency": "JPY" }

{ "id": "usr_01HX9G7..." }

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
        - name: cursor
          in: query
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id: { type: string, pattern: '^usr_' }
        email: { type: string, format: email }
        createdAt: { type: string, format: date-time }

import { z } from 'zod';
import { generateSchema } from '@anatine/zod-openapi';

export const User = z.object({
  id: z.string().startsWith('usr_'),
  email: z.string().email(),
  createdAt: z.string().datetime(),
});

export type User = z.infer<typeof User>;
const openApiSchema = generateSchema(User);

公開API:  URL path (v1, v2) + 日付ヘッダー
内部API:  Headerベース、rolling update
モバイル: URL path、古いアプリも長期サポート

GET /users?limit=20&offset=40

GET /users?limit=20&cursor=eyJpZCI6MTAwfQ==

{ "data": [...], "nextCursor": "eyJpZCI6MTIwfQ==", "hasMore": true }

-- 遅いoffset
SELECT * FROM users ORDER BY id LIMIT 20 OFFSET 100000;
-- 高速なkeyset
SELECT * FROM users WHERE id > 100020 ORDER BY id LIMIT 20;

「1 2 3 ... 10」UI → Offset
無限スクロール・API → Cursor
内部バッチ、大テーブル → Keyset

POST /charges HTTP/1.1
Idempotency-Key: f8a9b2c3-...-xyz
Content-Type: application/json

{ "amount": 10000, "currency": "JPY" }

1. Idempotency-Keyをチェック
2. 存在する場合:
   - 同じbody    → 保存済みレスポンス返却
   - 異なるbody  → 409 Conflict
3. 存在しない場合: 新規処理 + 結果を保存(24時間TTL)

async function idempotentHandler(req, res) {
  const key = req.headers['idempotency-key'];
  if (!key) return res.status(400).json({ error: 'Idempotency-Key required' });

  const lock = await redis.set(`lock:${key}`, '1', 'NX', 'EX', 30);
  if (!lock) await sleep(500);

  const cached = await redis.get(`idempotency:${key}`);
  if (cached) {
    const { bodyHash, response } = JSON.parse(cached);
    if (bodyHash !== hash(req.body)) {
      return res.status(409).json({ error: 'Conflicting request' });
    }
    return res.status(response.status).json(response.body);
  }

  const result = await processPayment(req.body);
  await redis.set(
    `idempotency:${key}`,
    JSON.stringify({ bodyHash: hash(req.body), response: { status: 200, body: result } }),
    'EX', 86400
  );
  return res.json(result);
}

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1697050800

# または RFC 9466 (draft):
RateLimit-Limit: 100, 100;w=60
RateLimit-Remaining: 42
RateLimit-Reset: 58

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{ "error": "Rate limit exceeded", "retryAfter": 60 }

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const [t, v1] = signature.split(',').map(s => s.split('=')[1]);
  const timestamp = parseInt(t);
  if (Math.abs(Date.now()/1000 - timestamp) > 300) return false;
  const expected = hmacSha256(secret, `${t}.${body}`);
  return timingSafeEqual(expected, v1);
}

1. 署名検証を最初に
2. Timestamp確認(5分以内)
3. Event IDで重複排除
4. 200を即返却、重い処理はキューへ
5. 非同期処理(Bull, Celeryなど)
6. 失敗時は5xxで発信側に再送させる

{
  "specversion": "1.0",
  "type": "com.example.order.created",
  "source": "/orders",
  "id": "evt_abc",
  "time": "2026-04-15T12:00:00Z",
  "datacontenttype": "application/json",
  "data": { "orderId": 123, "amount": 10000 }
}

asyncapi: 3.0.0
info:
  title: Order Service Events
  version: 1.0.0
channels:
  orderCreated:
    address: orders.created
    messages:
      orderCreatedMessage:
        payload:
          type: object
          properties:
            orderId: { type: string }
            amount: { type: integer }

REST + OpenAPI: 公開API、キャッシュ、多様なクライアント
GraphQL:        複雑なデータグラフ、フィールド選択
gRPC:           内部マイクロサービス、高性能、多言語
tRPC:           TSモノレポフルスタック、型自動

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization, Idempotency-Key
Access-Control-Max-Age: 86400

Sunset: Wed, 01 Jan 2027 00:00:00 GMT
Deprecation: true
Link: <https://docs.example.com/v2>; rel="successor-version"