REST API設計ベストプラクティス2025：開発者が知るべきAPI設計原則と実践パターン

# ステップ1：OpenAPI仕様を先に作成
openapi: 3.1.0
info:
  title: User Service API
  version: 1.0.0
paths:
  /api/v1/users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success

設計ワークフロー：
1. API仕様作成（OpenAPI）
2. 仕様レビューと合意
3. モックサーバーでフロントエンド開発開始
4. バックエンド実装
5. コントラクトテスト

POST /api HTTP/1.1
Content-Type: application/json

{
  "action": "getUser",
  "userId": 123
}

POST /api/users/123 HTTP/1.1
Content-Type: application/json

{
  "action": "get"
}

GET /api/users/123 HTTP/1.1
Accept: application/json

---

PUT /api/users/123 HTTP/1.1
Content-Type: application/json

{
  "name": "Updated Name",
  "email": "user@example.com"
}

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": { "href": "/api/v1/users/123" },
    "orders": { "href": "/api/v1/users/123/orders" },
    "update": { "href": "/api/v1/users/123", "method": "PUT" },
    "delete": { "href": "/api/v1/users/123", "method": "DELETE" }
  }
}

# コレクション
GET    /api/v1/users                    # ユーザー一覧
POST   /api/v1/users                    # ユーザー作成

# 個別リソース
GET    /api/v1/users/123                # 特定ユーザー取得
PUT    /api/v1/users/123                # ユーザー全体更新
PATCH  /api/v1/users/123                # ユーザー部分更新
DELETE /api/v1/users/123                # ユーザー削除

# ネストリソース
GET    /api/v1/users/123/orders         # ユーザーの注文一覧
GET    /api/v1/users/123/orders/456     # 特定注文取得
POST   /api/v1/users/123/orders         # 注文作成

# フィルタリング
GET    /api/v1/users?role=admin         # 管理者のみ取得
GET    /api/v1/products?category=electronics&min_price=100

# 検索
GET    /api/v1/users/search?q=john      # ユーザー検索

# 状態変更（アクション）
POST   /api/v1/users/123/activate       # アカウント有効化
POST   /api/v1/orders/456/cancel        # 注文キャンセル
POST   /api/v1/payments/789/refund      # 決済返金

# バッチ操作
POST   /api/v1/users/batch              # 一括作成
DELETE /api/v1/users/batch              # 一括削除

# サブリソース（シングルトン）
GET    /api/v1/users/123/profile        # ユーザープロフィール
PUT    /api/v1/users/123/avatar         # アバター更新

GET     リソース取得（読み取り）      — 安全、冪等
POST    リソース作成（書き込み）      — 安全でない、非冪等
PUT     リソース全体置換（上書き）    — 安全でない、冪等
PATCH   リソース部分更新             — 安全でない、非冪等（一般的に）
DELETE  リソース削除                 — 安全でない、冪等
OPTIONS サポートメソッド確認         — 安全、冪等
HEAD    GETと同一、本文なし          — 安全、冪等

// PUT：リソース全体置換（全フィールド必要）
// PUT /api/v1/users/123
{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "role": "admin"
}

// PATCH：部分更新（変更フィールドのみ）
// PATCH /api/v1/users/123
{
  "age": 31
}

POST /api/v1/users          -> サーバーがID生成（201 Created + Locationヘッダー）
PUT  /api/v1/users/123      -> クライアントがID指定（存在すれば置換、なければ作成）

リクエスト成功？
├── YES -> データ返却？     -> 200 OK
│         リソース作成？   -> 201 Created
│         非同期操作？     -> 202 Accepted
│         本文なし？       -> 204 No Content
└── NO  -> 認証問題？      -> 401 / 403
          リクエスト問題？ -> 400 / 422
          リソースなし？   -> 404
          競合？           -> 409
          サーバー問題？   -> 500 / 502 / 503

GET /api/v1/users?page=3&size=20

{
  "data": [
    { "id": 41, "name": "User 41" },
    { "id": 42, "name": "User 42" }
  ],
  "pagination": {
    "page": 3,
    "size": 20,
    "total_items": 1000,
    "total_pages": 50,
    "has_next": true,
    "has_prev": true
  }
}

-- SQL実装
SELECT * FROM users
ORDER BY id
LIMIT 20 OFFSET 40;
-- 問題：OFFSET 10000だと10000件をスキップ → パフォーマンス低下

GET /api/v1/users?cursor=eyJpZCI6NDJ9&limit=20

{
  "data": [
    { "id": 43, "name": "User 43" },
    { "id": 44, "name": "User 44" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6NjJ9",
    "has_next": true,
    "limit": 20
  }
}

// Node.js実装
async function getCursorPaginatedUsers(cursor, limit = 20) {
  let query = 'SELECT * FROM users'
  const params = []

  if (cursor) {
    const decoded = JSON.parse(Buffer.from(cursor, 'base64').toString())
    query += ' WHERE id > $1'
    params.push(decoded.id)
  }

  query += ' ORDER BY id ASC LIMIT $' + (params.length + 1)
  params.push(limit + 1) // +1で次ページ存在確認

  const rows = await db.query(query, params)
  const hasNext = rows.length > limit
  const data = hasNext ? rows.slice(0, limit) : rows

  const nextCursor = hasNext
    ? Buffer.from(JSON.stringify({ id: data[data.length - 1].id })).toString('base64')
    : null

  return { data, pagination: { next_cursor: nextCursor, has_next: hasNext, limit } }
}

GET /api/v1/users?after_date=2025-01-15&after_id=42&limit=20&sort=created_at

-- SQL実装：created_at + id複合キー
SELECT * FROM users
WHERE (created_at, id) > ('2025-01-15', 42)
ORDER BY created_at ASC, id ASC
LIMIT 20;

# 単純フィルタ
GET /api/v1/products?category=electronics&brand=apple

# 比較演算子
GET /api/v1/products?price_gte=100&price_lte=500

# 配列フィルタ
GET /api/v1/products?tags=wireless,bluetooth

# 日付範囲
GET /api/v1/orders?created_after=2025-01-01&created_before=2025-03-31

# 単一ソート
GET /api/v1/products?sort=price

# 降順
GET /api/v1/products?sort=-price

# 複合ソート
GET /api/v1/products?sort=-created_at,name

# 必要なフィールドのみリクエスト（レスポンスサイズ削減）
GET /api/v1/users?fields=id,name,email

# 関連リソースを含める
GET /api/v1/users/123?include=orders,profile

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

# RQL（Resource Query Language）スタイル
GET /api/v1/products?filter=category==electronics;price=gt=100;brand=in=(apple,samsung)

GET /api/v1/users/123
GET /api/v2/users/123

GET /api/users/123
Accept: application/vnd.myapp.v2+json

GET /api/users/123?version=2

1. メジャーバージョンのみ管理（v1、v2）— Minor/Patchは後方互換
2. 最低2バージョン同時サポート
3. 非推奨ポリシー公開（最低6ヶ月の猶予期間）
4. Sunsetヘッダー使用

  Sunset: Sat, 01 Mar 2026 00:00:00 GMT
  Deprecation: true
  Link: <https://api.example.com/v2/users>; rel="successor-version"

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Failed",
  "status": 422,
  "detail": "リクエスト本文に無効なフィールドがあります。",
  "instance": "/api/v1/users",
  "timestamp": "2025-03-15T10:30:00Z",
  "errors": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "有効なメールアドレスを入力してください。"
    },
    {
      "field": "age",
      "code": "OUT_OF_RANGE",
      "message": "年齢は0から150の間でなければなりません。"
    }
  ]
}

// エラークラス定義
class ApiError extends Error {
  constructor(status, type, title, detail, errors = []) {
    super(detail)
    this.status = status
    this.type = type
    this.title = title
    this.detail = detail
    this.errors = errors
  }
}

// ファクトリ関数
const ApiErrors = {
  notFound: (resource, id) =>
    new ApiError(
      404,
      'https://api.example.com/errors/not-found',
      'Resource Not Found',
      `${resource} with id ${id} was not found.`
    ),

  validationFailed: (errors) =>
    new ApiError(
      422,
      'https://api.example.com/errors/validation',
      'Validation Failed',
      'The request body contains invalid fields.',
      errors
    ),

  rateLimited: (retryAfter) =>
    new ApiError(
      429,
      'https://api.example.com/errors/rate-limit',
      'Rate Limit Exceeded',
      `Too many requests. Retry after ${retryAfter} seconds.`
    ),
}

// Expressエラーハンドラー
app.use((err, req, res, next) => {
  if (err instanceof ApiError) {
    return res.status(err.status).json({
      type: err.type,
      title: err.title,
      status: err.status,
      detail: err.detail,
      instance: req.originalUrl,
      timestamp: new Date().toISOString(),
      errors: err.errors.length > 0 ? err.errors : undefined,
    })
  }

  // 予期せぬエラー
  console.error('Unexpected error:', err)
  res.status(500).json({
    type: 'https://api.example.com/errors/internal',
    title: 'Internal Server Error',
    status: 500,
    detail: 'An unexpected error occurred.',
    instance: req.originalUrl,
    timestamp: new Date().toISOString(),
  })
})

// i18nエラーメッセージ
const errorMessages = {
  INVALID_EMAIL: {
    ko: '유효한 이메일 주소를 입력하세요.',
    en: 'Please enter a valid email address.',
    ja: '有効なメールアドレスを入力してください。',
  },
  FIELD_REQUIRED: {
    ko: '필수 입력 항목입니다.',
    en: 'This field is required.',
    ja: '必須入力項目です。',
  },
}

function getErrorMessage(code, lang = 'en') {
  return errorMessages[code]?.[lang] || errorMessages[code]?.['en'] || code
}

バケット容量：100トークン
補充速度：10トークン/秒

[リクエスト到着] → バケットにトークンあり？ → YES → トークン消費、リクエスト処理
                                            → NO  → 429レスポンス

class TokenBucket {
  constructor(capacity, refillRate) {
    this.capacity = capacity
    this.tokens = capacity
    this.refillRate = refillRate
    this.lastRefill = Date.now()
  }

  consume() {
    this.refill()
    if (this.tokens > 0) {
      this.tokens--
      return true
    }
    return false
  }

  refill() {
    const now = Date.now()
    const elapsed = (now - this.lastRefill) / 1000
    this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate)
    this.lastRefill = now
  }
}

class SlidingWindowLog {
  constructor(windowMs, maxRequests) {
    this.windowMs = windowMs
    this.maxRequests = maxRequests
    this.logs = new Map() // key -> timestamps[]
  }

  isAllowed(key) {
    const now = Date.now()
    const windowStart = now - this.windowMs

    if (!this.logs.has(key)) {
      this.logs.set(key, [])
    }

    const timestamps = this.logs.get(key).filter((ts) => ts > windowStart)
    this.logs.set(key, timestamps)

    if (timestamps.length < this.maxRequests) {
      timestamps.push(now)
      return true
    }

    return false
  }
}

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1678886400

---

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1678886400
Retry-After: 30
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/rate-limit",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit. Please retry after 30 seconds."
}

Authorization Code Flow（サーバーアプリ）：
1. ユーザー → 認証サーバー（ログイン）
2. 認証サーバー → クライアント（Authorization Code）
3. クライアント → 認証サーバー（Code + Client Secret → Access Token）
4. クライアント → リソースサーバー（Access Token）

Authorization Code + PKCE（SPA/モバイル）：
1. code_verifier生成
2. code_challenge = SHA256(code_verifier)
3. 認証リクエストにcode_challengeを含める
4. トークン交換時にcode_verifierを送信して検証

1. Access Token有効期限：15分（最大1時間）
2. Refresh Token有効期限：7日（最大30日）
3. 署名アルゴリズム：RS256（非対称）またはES256推奨
4. ペイロードに機密情報を入れないこと
5. aud、iss、expクレームを必ず検証
6. httpOnlyクッキーに保存（XSS防止）
7. Token Rotation適用

# ヘッダー方式（推奨）
GET /api/v1/users HTTP/1.1
Authorization: Bearer access_token_here
X-API-Key: api_key_here

# URLに含めないこと
# 悪い例: /api/v1/users?api_key=abc123

// Express CORS設定
const cors = require('cors')

app.use(
  cors({
    origin: ['https://app.example.com', 'https://admin.example.com'],
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
    allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key'],
    credentials: true,
    maxAge: 86400, // Preflightキャッシュ24時間
  })
)

// Zodを使用したリクエスト検証
const { z } = require('zod')

const CreateUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  age: z.number().int().min(0).max(150).optional(),
  role: z.enum(['user', 'admin', 'moderator']).default('user'),
})

// ミドルウェア
function validate(schema) {
  return (req, res, next) => {
    const result = schema.safeParse(req.body)
    if (!result.success) {
      return res.status(422).json({
        type: 'https://api.example.com/errors/validation',
        title: 'Validation Failed',
        status: 422,
        errors: result.error.issues.map((issue) => ({
          field: issue.path.join('.'),
          code: issue.code,
          message: issue.message,
        })),
      })
    }
    req.body = result.data
    next()
  }
}

app.post('/api/v1/users', validate(CreateUserSchema), createUser)

openapi: 3.1.0
info:
  title: E-Commerce API
  description: E-Commerce REST API
  version: 1.0.0
  contact:
    name: API Team
    email: api@example.com

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

paths:
  /products:
    get:
      operationId: listProducts
      tags: [Products]
      summary: List all products
      parameters:
        - name: category
          in: query
          schema:
            type: string
        - name: sort
          in: query
          schema:
            type: string
            enum: [price, -price, name, -name, created_at]
        - name: cursor
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  pagination:
                    $ref: '#/components/schemas/CursorPagination'
        '429':
          $ref: '#/components/responses/RateLimited'

components:
  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
          minLength: 1
          maxLength: 200
        price:
          type: number
          format: decimal
          minimum: 0
        category:
          type: string
        created_at:
          type: string
          format: date-time

    CursorPagination:
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        has_next:
          type: boolean
        limit:
          type: integer

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - BearerAuth: []
  - ApiKeyAuth: []

# OpenAPI GeneratorでクライアントSDK生成
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./generated/client

# サーバースタブ生成
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g nodejs-express-server \
  -o ./generated/server

// Postman Test Script例
pm.test('Status code is 200', () => {
  pm.response.to.have.status(200)
})

pm.test('Response has correct structure', () => {
  const json = pm.response.json()
  pm.expect(json).to.have.property('data')
  pm.expect(json.data).to.be.an('array')
  pm.expect(json).to.have.property('pagination')
})

pm.test('Pagination cursor exists', () => {
  const json = pm.response.json()
  if (json.data.length > 0) {
    pm.expect(json.pagination).to.have.property('next_cursor')
  }
})

# NewmanでCI/CDパイプラインで実行
newman run collection.json \
  --environment production.json \
  --reporters cli,junit \
  --reporter-junit-export results.xml

// Consumer Test（フロントエンド）
const { PactV3 } = require('@pact-foundation/pact')

const provider = new PactV3({
  consumer: 'WebApp',
  provider: 'UserService',
})

describe('User API', () => {
  it('fetches a user by ID', async () => {
    await provider
      .given('user 123 exists')
      .uponReceiving('a request for user 123')
      .withRequest({
        method: 'GET',
        path: '/api/v1/users/123',
        headers: { Accept: 'application/json' },
      })
      .willRespondWith({
        status: 200,
        headers: { 'Content-Type': 'application/json' },
        body: {
          id: 123,
          name: 'John Doe',
          email: 'john@example.com',
        },
      })
      .executeTest(async (mockServer) => {
        const response = await fetch(`${mockServer.url}/api/v1/users/123`, {
          headers: { Accept: 'application/json' },
        })
        expect(response.status).toBe(200)
      })
  })
})

// k6ロードテスト
import http from 'k6/http'
import { check, sleep } from 'k6'

export const options = {
  stages: [
    { duration: '30s', target: 50 }, // ランプアップ
    { duration: '1m', target: 100 }, // 維持
    { duration: '30s', target: 0 }, // ランプダウン
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'], // 95%のリクエストが500ms以内
    http_req_failed: ['rate<0.01'], // エラー率1%未満
  },
}

export default function () {
  const res = http.get('https://api.example.com/v1/products?limit=20')

  check(res, {
    'status is 200': (r) => r.status === 200,
    'response time < 500ms': (r) => r.timings.duration < 500,
    'has data array': (r) => JSON.parse(r.body).data.length > 0,
  })

  sleep(1)
}

Stripeのコア設計原則：
1. 一貫したリソース命名（/v1/customers、/v1/charges、/v1/subscriptions）
2. Expandパラメータで関連リソースを含む
3. 冪等性キー（Idempotency-Keyヘッダー）
4. 詳細なエラーレスポンス
5. 自動ページネーション（has_more + starting_after）

# Stripeスタイルリクエスト
POST /v1/charges HTTP/1.1
Authorization: Bearer sk_test_xxx
Idempotency-Key: unique-request-id-123
Content-Type: application/x-www-form-urlencoded

amount=2000&currency=usd&source=tok_visa

GitHub APIの特徴：
1. REST + GraphQLハイブリッド
2. 条件付きリクエスト（ETag、If-None-Match）
3. Linkヘッダーページネーション
4. Hypermedia（URLテンプレート）
5. Rate Limitの明確な表示

# GitHub条件付きリクエスト
GET /repos/octocat/hello-world HTTP/1.1
If-None-Match: "etag-value"

# 304 Not Modified（キャッシュ使用）
# または 200 OK（新しいETag含む）

Twitter API v2の特徴：
1. フィールド選択（fieldsパラメータ）
2. Expansionで関連オブジェクトを含む
3. ストリーミングエンドポイント
4. 細分化されたRate Limit
5. OAuth2 + App-only Auth

# Twitterスタイル：フィールド選択 + expansion
GET /2/tweets?ids=123,456&tweet.fields=created_at,public_metrics&expansions=author_id&user.fields=username