APIデザインパターン

REST、GraphQL、gRPCのための実証済みパターンを使用して、適切なバージョニング、認証、エラーハンドリングで堅牢でスケーラブルなAPIを設計します。

クイックリファレンス

APIスタイルの選択:

• REST: リソースベースのCRUD、シンプルなクライアント、HTTP標準のキャッシング
• GraphQL: クライアント駆動型のクエリ、複雑なデータグラフ、リアルタイムサブスクリプション
• gRPC: 高パフォーマンスRPC、マイクロサービス、強力な型付け、ストリーミング

重要なパターン:

• バージョニング: URI (/v1/users)、ヘッダー (Accept: application/vnd.api+json;version=1)、コンテンツネゴシエーション
• ページネーション: オフセット (シンプル)、カーソル (安定)、キーセット (高性能)
• 認証: OAuth2 (委譲)、JWT (ステートレス)、APIキー (サービス間通信)
• レート制限: トークンバケット、固定ウィンドウ、スライディングウィンドウ
• べき等性: べき等性キー、条件付きリクエスト、安全な再試行

詳細は参考資料を参照: rest-patterns.md、graphql-patterns.md、grpc-patterns.md、versioning-strategies.md、authentication.md

コアプリンシパル

ユニバーサルAPI設計標準

すべてのAPIスタイルに適用する原則:

1. 巧妙さより一貫性

• あなたのAPIスタイル用に確立された規約に従う
• 予測可能な命名パターンを使用する (snake_case または camelCase、どちらかを選ぶ)
• 一貫したエラーレスポンス形式を維持する
• 重大な変更をバージョニングし、クライアントを驚かさない

2. 進化に向けた設計

• 初日からバージョニングを計画する
• 合理的なデフォルトを使用したオプショナルフィールドを使用する
• グレースフルな廃止とサンセット日付を実施する
• 重大な変更と非重大な変更を文書化する

3. デフォルトでセキュア

• 明示的に公開される場合を除き、認証が必須
• すべての本番エンドポイントでHTTPS/TLSを使用する
• レート制限とスロットリングを実装する
• すべての入力を検証してサニタイズする
• クライアントに最小限のエラー詳細を返す

4. 開発者体験を最優先

• 包括的なドキュメント (OpenAPI、GraphQLスキーマ) を提供する
• 実行可能なガイダンス付きの意味のあるエラーメッセージを返す
• 標準的なHTTPステータスコードを正しく使用する
• デバッグ用のリクエストIDを含める
• SDKとコードジェネレータを提供する

APIスタイル判定フロー

RESTを選択する場合

✅ 以下の場合にRESTを使用:

• CRUD中心のリソースAPIの構築
• クライアントがHTTPキャッシング (ETag、Cache-Control) が必要
• 広範なプラットフォーム互換性が必要 (ブラウザ、モバイル、IoT)
• シンプルでステートレスなクライアント・サーバーモデルが適している
• チームがHTTP/REST規約に精通している

❌ RESTを避ける場合:

• ネストされた関係を持つ複雑なデータ取得 (N+1クエリ)
• リアルタイム更新がプライマリなユースケース
• 強力な型付けとコード生成が必要
• マイクロサービス間の高パフォーマンスRPC

ユースケース例: パブリックAPI、モバイルバックエンド、従来のWebサービス

GraphQLを選択する場合

✅ 以下の場合にGraphQLを使用:

• クライアントが柔軟なクライアント駆動型クエリが必要
• ネストされた関係を持つ複雑なデータグラフ
• 異なるデータニーズを持つ複数のクライアントタイプ
• リアルタイムサブスクリプションが必要
• 強力な型付けとスキーマ検証が必要

❌ GraphQLを避ける場合:

• シンプルなCRUD操作が主体
• HTTPキャッシングが重要 (GraphQLはPOSTを使用)
• ファイルアップロードがプライマリ機能 (拡張が必要)
• チームがGraphQLの専門知識を欠いている
• パフォーマンス最適化が複雑 (N+1問題)

ユースケース例: クライアント向けAPI、ダッシュボード、さまざまなUIを持つモバイルアプリ

gRPCを選択する場合

✅ 以下の場合にgRPCを使用:

• マイクロサービス間通信
• 高パフォーマンスと低レイテンシーが重要
• 双方向ストリーミングが必要
• Protocol Buffersによる強力な型付け
• ポリグロット環境 (言語間相互運用性)

❌ gRPCを避ける場合:

• ブラウザクライアント (サポートが限定的、grpc-web が必要)
• HTTP/JSONが互換性に必要
• 人間が読める形式のペイロードを推奨
• シンプルなリクエスト/レスポンスパターン

ユースケース例: 内部マイクロサービス、ストリーミングデータ、サービスメッシュ

REST APIパターン

リソース命名

✅ 良い例: 複数形の名詞、階層構造

GET    /users              # ユーザーのリスト
GET    /users/123          # ユーザーを取得
POST   /users              # ユーザーを作成
PUT    /users/123          # ユーザーを更新 (完全)
PATCH  /users/123          # ユーザーを更新 (部分)
DELETE /users/123          # ユーザーを削除
GET    /users/123/orders   # ユーザーの注文 (サブリソース)

❌ 悪い例: 動詞、混合された規約

GET    /getUsers           # 動詞を使用しない
POST   /user/create        # 動詞を使用しない
GET    /Users/123          # 大文字を使用しない
GET    /user/123           # 単数形と複数形を混ぜない

HTTPステータスコード

成功コード:

• 200 OK: GET、PUT、PATCH、DELETEが成功し、ボディがある
• 201 Created: POST成功、Locationヘッダーを返す
• 202 Accepted: 非同期操作が開始された
• 204 No Content: DELETE成功、ボディなし

クライアントエラーコード:

• 400 Bad Request: 無効な入力、検証エラー
• 401 Unauthorized: 認証がないか無効
• 403 Forbidden: 認証されているが権限不足
• 404 Not Found: リソースが存在しない
• 409 Conflict: 状態の競合 (重複、バージョン不一致)
• 422 Unprocessable Entity: セマンティック検証エラー
• 429 Too Many Requests: レート制限超過

サーバーエラーコード:

• 500 Internal Server Error: 予期しないエラー
• 502 Bad Gateway: アップストリームサービスエラー
• 503 Service Unavailable: 一時的な障害
• 504 Gateway Timeout: アップストリームタイムアウト

エラーレスポンス形式

✅ 一貫したエラー構造

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "無効なリクエストパラメータ",
    "details": [
      {
        "field": "email",
        "message": "無効なメールアドレス形式",
        "code": "INVALID_FORMAT"
      }
    ],
    "request_id": "req_abc123",
    "documentation_url": "https://api.example.com/docs/errors/validation"
  }
}

ページネーションパターン

オフセットページネーション (シンプル、使い慣れた):

GET /users?limit=20&offset=40

✅ 以下の用途: 小規模データセット、管理インターフェース ❌ 以下を避ける: 大規模データセット (スキップが高コスト)、リアルタイムデータ

カーソルページネーション (安定、効率的):

GET /users?limit=20&cursor=eyJpZCI6MTIzfQ
Response: { "data": [...], "next_cursor": "eyJpZCI6MTQzfQ" }

✅ 以下の用途: 無限スクロール、リアルタイムフィード、大規模データセット ❌ 以下を避ける: ランダムアクセス、ページ番号

キーセットページネーション (高性能):

GET /users?limit=20&after_id=123

✅ 以下の用途: 順序付きデータ、データベースインデックス対応 ❌ 以下を避ける: 複雑なソート、複数のソートキー

詳細は references/rest-patterns.md でフィルタリング、ソート、フィールド選択、HATEOAS を参照してください。

GraphQLパターン

スキーマ設計

✅ 良い例: クリアな型、デフォルトでnullable

type User {
  id: ID!                    # Non-null ID
  email: String!             # 必須フィールド
  name: String               # オプショナル (デフォルトでnullable)
  createdAt: DateTime!
  orders: [Order!]!          # Non-null配列のnon-nullオーダー
}

type Query {
  user(id: ID!): User
  users(first: Int, after: String): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

input CreateUserInput {
  email: String!
  name: String
}

type CreateUserPayload {
  user: User
  userEdge: UserEdge
  errors: [UserError!]
}

リゾルバーパターン

DataLoaderでN+1クエリを回避:

import DataLoader from 'dataloader';

const userLoader = new DataLoader(async (userIds: string[]) => {
  const users = await db.users.findMany({ where: { id: { in: userIds } } });
  return userIds.map(id => users.find(u => u.id === id));
});

// リゾルバーが自動的にクエリをバッチ処理
const resolvers = {
  Order: {
    user: (order) => userLoader.load(order.userId)
  }
};

クエリ複雑性分析

高コストなクエリを防止:

import { createComplexityLimitRule } from 'graphql-validation-complexity';

const server = new ApolloServer({
  schema,
  validationRules: [
    createComplexityLimitRule(1000, {
      onCost: (cost) => console.log('Query cost:', cost),
    }),
  ],
});

詳細は references/graphql-patterns.md でサブスクリプション、Relayカーソル接続、エラーハンドリング を参照してください。

gRPCパターン

サービス定義

syntax = "proto3";

package users.v1;

service UserService {
  rpc GetUser (GetUserRequest) returns (User) {}
  rpc ListUsers (ListUsersRequest) returns (ListUsersResponse) {}
  rpc CreateUser (CreateUserRequest) returns (User) {}
  rpc StreamUsers (StreamUsersRequest) returns (stream User) {}
  rpc BidiChat (stream ChatMessage) returns (stream ChatMessage) {}
}

message User {
  string id = 1;
  string email = 2;
  string name = 3;
  google.protobuf.Timestamp created_at = 4;
}

message GetUserRequest {
  string id = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
}

message ListUsersResponse {
  repeated User users = 1;
  string next_page_token = 2;
}

エラーハンドリング

import (
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

func (s *server) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
    if req.Id == "" {
        return nil, status.Error(codes.InvalidArgument, "user ID is required")
    }

    user, err := s.db.GetUser(ctx, req.Id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, status.Error(codes.NotFound, "user not found")
        }
        return nil, status.Error(codes.Internal, "database error")
    }

    return user, nil
}

詳細は references/grpc-patterns.md でストリーミング、インターセプタ、メタデータ、ヘルスチェック を参照してください。

バージョニング戦略

URIバージョニング (シンプル、明示的)

✅ 最も一般的、理解しやすい

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

メリット: クリア、ルーティングが簡単、ブラウザフレンドリー デメリット: バージョンがURLに結合される、ルートが複製される

ヘッダーバージョニング (クリアなURL)

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

メリット: クリアなURL、バージョンがリソースと分離 デメリット: 見えにくい、手動テストが難しい

コンテンツネゴシエーション (粒度の高い)

GET /users/123
Accept: application/vnd.myapi.user.v2+json

メリット: リソースレベルのバージョニング、後方互換性 デメリット: 複雑、実装が難しい

バージョン廃止プロセス

{
  "version": "1.0",
  "deprecated": true,
  "sunset_date": "2025-12-31",
  "migration_guide": "https://docs.api.com/v1-to-v2",
  "replacement_version": "2.0"
}

廃止警告を含める:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: <https://docs.api.com/v1-to-v2>; rel="deprecation"

詳細は references/versioning-strategies.md で詳細なマイグレーションパターン を参照してください。

認証と認可

OAuth 2.0 (委譲アクセス)

用途: サードパーティアクセス、ユーザー同意、トークンリフレッシュ

認可コードフロー (Web/モバイル用、最もセキュア):

1. クライアントが /authorize にリダイレクト
2. ユーザーが認証し、権限を付与
3. 認可サーバーがコード付きでコールバックにリダイレクト
4. クライアントがコードをアクセストークンと交換
5. クライアントがアクセストークンを使用してAPI要求

# トークン要求
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://client.com/callback
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET

# レスポンス
{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "read write"
}

# トークンを使用
GET /v1/users/me
Authorization: Bearer eyJhbGc...

JWT (ステートレス認証)

用途: マイクロサービス、ステートレスAPI認証、短命トークン

✅ 良い例: 最小限のクレーム、短い有効期限

{
  "sub": "user_123",
  "iat": 1516239022,
  "exp": 1516242622,
  "scope": "read:users write:orders"
}

検証:

import jwt from 'jsonwebtoken';

const token = req.headers.authorization?.split(' ')[1];
const payload = jwt.verify(token, process.env.JWT_SECRET);
req.userId = payload.sub;

APIキー (サービス間通信)

用途: サーバー間、CLIツール、ウェブフック

GET /v1/users
X-API-Key: sk_live_abc123...

# またはクエリパラメータ (セキュリティが低い)
GET /v1/users?api_key=sk_live_abc123

キー慣行:

• キーを環境でプレフィックス (sk_live_、sk_test_)
• 保存前にキーをハッシュ (bcrypt、scrypt)
• ダウンタイムなしでキーローテーションを許可
• ユーザーごとに複数のキーをサポート
• キーごとにレート制限

詳細は references/authentication.md でAPIキーローテーション、スコープ、RBAC を参照してください。

レート制限

トークンバケット (バースト対応)

バケット: 100トークン、毎秒10個補充
リクエスト1トークンを消費
バケットサイズまでのバースト許可

ヘッダー:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1640995200

429レスポンス:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "レート制限に達しました。60秒後に再度お試しください。",
    "limit": 100,
    "reset_at": "2025-01-01T00:00:00Z"
  }
}

スライディングウィンドウ (公正な分配)

ローリング時間ウィンドウ内のリクエストをカウント。固定ウィンドウより正確。

ユーザーごと対 IP毎

• ユーザーごと: 認証済みリクエスト、公正なクォータ
• IP毎: 未認証リクエスト、悪用防止
• 組み合わせ: 両方の制限、より厳しい方を適用

べき等性

べき等メソッド (HTTP仕様)

自然にべき等: GET、PUT、DELETE、HEAD、OPTIONS べき等でない: POST、PATCH

べき等性キー

POSTリクエストをべき等にする:

POST /v1/payments
Idempotency-Key: uuid-or-client-generated-key
Content-Type: application/json

{
  "amount": 1000,
  "currency": "USD",
  "customer": "cust_123"
}

サーバー動作:

1. 最初のリクエスト: 処理してキーと一緒に結果を保存
2. 重複リクエスト (同じキー): 保存された結果を返す (200または201)
3. 異なるリクエスト (同じキー): 409 Conflict を返す

実装:

const idempotencyKey = req.headers['idempotency-key'];
if (idempotencyKey) {
  const cached = await redis.get(`idempotency:${idempotencyKey}`);
  if (cached) {
    return res.status(cached.status).json(cached.body);
  }
}

const result = await processPayment(req.body);
await redis.setex(`idempotency:${idempotencyKey}`, 86400, {
  status: 201,
  body: result
});

条件付きリクエスト

ETagを使用して安全に更新:

# ETag付きリソースを取得
GET /v1/users/123
Response: ETag: "abc123"

# 変更されていない場合のみ更新
PUT /v1/users/123
If-Match: "abc123"

# ETagが変更された場合は 412 Precondition Failed

キャッシング戦略

HTTPキャッシングヘッダー

# パブリック、1時間キャッシュ可能
Cache-Control: public, max-age=3600

# プライベート (ユーザー固有)、再検証
Cache-Control: private, must-revalidate, max-age=0

# キャッシングなし
Cache-Control: no-store, no-cache, must-revalidate

ETag検証

# サーバーがETagを返す
GET /v1/users/123
Response:
  ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
  Cache-Control: max-age=3600

# クライアント条件付きリクエスト
GET /v1/users/123
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

# 変更されていない場合は 304 Not Modified (帯域幅節約)
HTTP/1.1 304 Not Modified

Last-Modified

GET /v1/users/123
Response:
  Last-Modified: Wed, 21 Oct 2025 07:28:00 GMT

# 条件付きリクエスト
GET /v1/users/123
If-Modified-Since: Wed, 21 Oct 2025 07:28:00 GMT

# 変更されていない場合は 304 Not Modified

ウェブフック

イベント配信

POST https://client.com/webhooks/payments
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-Id: evt_abc123
X-Webhook-Timestamp: 1640995200

{
  "id": "evt_abc123",
  "type": "payment.succeeded",
  "created": 1640995200,
  "data": {
    "object": {
      "id": "pay_123",
      "amount": 1000,
      "status": "succeeded"
    }
  }
}

シグネチャ検証

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

再試行戦略

• 指数バックオフ: 1秒、2秒、4秒、8秒、16秒、32秒、64秒
• タイムアウト: 試行あたり5～30秒
• 最大試行: 3～7回
• デッドレターキュー: 失敗したイベントを保存
• 手動再試行: 失敗したイベント再送用UI

APIドキュメント

OpenAPI/Swagger (REST)

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: IDでユーザーを取得
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功レスポンス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: ユーザーが見つかりません
components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string

GraphQLスキーマ (自動文書化)

GraphQLイントロスペクションは自動ドキュメント化を提供します。説明を使用してください:

"""
システム内のユーザーアカウントを表します。
createUser mutationを使用して作成されます。
"""
type User {
  """ユーザーの一意識別子"""
  id: ID!

  """メールアドレス、一意である必要があります"""
  email: String!

  """オプショナルな表示名"""
  name: String
}

APIドキュメントのベストプラクティス

1. インタラクティブな例: 実装可能なコードサンプルを提供
2. 認証ガイド: ステップバイステップの認証セットアップ
3. エラーカタログ: すべてのエラーコードを例付きで文書化
4. レート制限: 制限とヘッダーを明確に記述
5. 変更ログ: 重大な変更と非重大な変更を追跡
6. マイグレーションガイド: バージョンアップグレード手順
7. SDK: 人気のある言語のクライアントライブラリを提供

アンチパターン

❌ オーバーフェッチング (REST): 未使用フィールド時に全オブジェクトを返す ✅ 解決策: フィールド選択をサポート (?fields=id,name,email)

❌ アンダーフェッチング (REST): 関連データに複数リクエストが必要 ✅ 解決策: 展開をサポート (?expand=orders,profile) またはGraphQLを使用

❌ チャッティなAPI: 一般的な操作に多すぎるラウンドトリップ ✅ 解決策: バッチエンドポイント、複合ドキュメント、またはGraphQL

❌ HTTP意味論を無視: GET をmutationに使用、間違ったステータスコード ✅ 解決策: HTTP仕様に従う、正しいメソッドとステータスコードを使用

❌ 内部構造を公開: URL/スキーマがデータベースを反映 ✅ 解決策: ストレージから独立した、リソース指向のAPIを設計

❌ バージョニングなし: バージョンがないまま重大な変更 ✅ 解決策: 初日からバージョニング、既存バージョンを破壊しない

❌ 貧弱なエラーメッセージ: 一般的な「エラーが発生しました」 ✅ 解決策: 具体的で実行可能なエラーメッセージとコード

❌ レート制限なし: APIが悪用に対して脆弱 ✅ 解決策: 最初からレート制限を実装

テスト戦略

コントラクトテスト

// Pactコントラクトテスト
import { PactV3 } from '@pact-foundation/pact';

const provider = new PactV3({
  consumer: 'FrontendApp',
  provider: 'UserAPI'
});

it('gets a user by ID', () => {
  provider
    .given('user 123 exists')
    .uponReceiving('a request for user 123')
    .withRequest({
      method: 'GET',
      path: '/users/123'
    })
    .willRespondWith({
      status: 200,
      body: { id: '123', email: 'user@example.com' }
    });
});

ロードテスト

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

export const options = {
  stages: [
    { duration: '30s', target: 20 },
    { duration: '1m', target: 20 },
    { duration: '10s', 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/users');
  check(res, {
    'status is 200': (r) => r.status === 200,
    'response time < 500ms': (r) => r.timings.duration < 500
  });
}

関連スキル

• graphql: GraphQLスキーマ設計、リゾルバー、Apollo Server
• typescript: 型安全なAPIクライアントとサーバー
• nodejs-backend: Express/Fastify REST API実装
• django: Django REST Frameworkパターン
• fastapi: FastAPI Python REST/GraphQL API
• flask: Flask-RESTfulパターン

参考資料

• rest-patterns.md: REST詳細カバー (HATEOAS、フィルタリング、フィールド選択)
• graphql-patterns.md: GraphQLサブスクリプション、Relayカーソル接続、フェデレーション
• grpc-patterns.md: ストリーミングパターン、インターセプタ、サービスメッシュ統合
• versioning-strategies.md: 詳細なバージョニングアプローチとマイグレーションパターン
• authentication.md: OAuthフロー、JWTベストプラクティス、APIキーローテーション、RBAC

追加リソース

• REST API Design Rulebook - O'Reilly REST ガイド
• GraphQL Best Practices - 公式GraphQLガイド
• gRPC Best Practices - 公式gRPCガイド
• RFC 7807: Problem Details for HTTP APIs - 標準エラー形式
• OpenAPI Specification - REST ドキュメント標準