エンタープライズマイクロサービスアーキテクチャ向けREST API設計方法

マイクロサービスにおいてREST API設計がより重要な理由

モノリスにおける設計の粗いAPIは不便な程度ですが、マイクロサービスアーキテクチャでは連鎖的な負債となります。サービス間の呼び出しはすべてネットワーク境界を越えており、レイテンシー、障害モード、バージョニングへの影響が伴います。20以上のマイクロサービスを運用するエンタープライズチームは、最大のボトルネックがコンピュートやストレージではなくAPIコントラクトの不整合にあることをしばしば発見します。意図的なREST API設計への投資は複利的なリターンをもたらします。

ドメイン駆動リソースモデリングから始める

• APIリソースはデータベーススキーマではなく境界付けられたコンテキストにマッピングしてください。各マイクロサービスはそのドメインを所有し、ビジネス機能を表すリソースを公開します。
• リソース名には動詞ではなく名詞を使用してください。POST /orders は正しい形式です。POST /createOrder はRESTを装ったRPCパターンです。
• 厳密な所有関係がある場合にのみリソースをネストしてください。/orders/{id}/items は合理的です。/users/{id}/recommendations はおそらく独自のサービスに属します。
• リソースの粒度のバランスを保ってください。細かすぎるとAPIが饒舌になり、粗すぎると神サービスが生まれます。
• 集約ルートを明確に定義してください。親を削除する際に子へカスケードすべき場合は、同じAPIに属します。

本番環境に耐えるAPIバージョニング戦略

バージョニングをスキップしたエンタープライズチームは、6か月以内に後悔することになります。問題はバージョン管理するかどうかではなく、どの戦略が調整コストを最小化するかです。

• 外部APIにはURIパスバージョニング（/v1/orders）を使用してください。明示的でキャッシュフレンドリーであり、ヘッダーの検査が不要です。
• サービス間の内部呼び出しにはヘッダーベースのバージョニングを使用し、URIをクリーンに保ちます。
• 廃止ポリシー：削除の2リリースサイクル前に告知し、Sunsetヘッダーを返してください。
• メジャーバージョン内で後方互換性を絶対に壊さないでください。追加的な変更のみを許容します。
• 本番前に破壊的変更を検出するため、コントラクトテスト（Pact、Spring Cloud Contract）を実施してください。

サービス境界を越えた認証と認可

マイクロサービスにおけるセキュリティは単一のチェックポイントではなく、外部アクセス制御と内部サービス信頼のバランスをとる階層的な戦略です。

• 外部トラフィックの単一エントリポイントとしてAPIゲートウェイを使用し、OAuth 2.0トークン検証を行ってください。
• ユーザーID、ロール、テナントIDのスコープ付きクレームを持つJWTトークンを発行し、ダウンストリームサービスが追加のルックアップなしに認可できるようにしてください。
• サービス間呼び出しには相互TLS（mTLS）またはマシン間OAuthトークンを使用してください。サービス間でユーザー認証情報を渡すことは絶対に避けてください。
• APIレベルで最小権限を実装してください。各サービスはコンシューマーが実際に必要とするものだけを公開します。
• ID管理を一元化しながら、認可の判断は各サービスドメインに分散させてください。

エラーハンドリングとレジリエンスパターン

• エラーレスポンスにはRFC 7807 Problem Details形式を使用してください。全サービスで構造を標準化します。
• 適切なHTTPステータスコードを返してください。クライアントエラーには行動可能なメッセージを添えた400番台、サーバーエラーには相関IDを添えた500番台です。
• サービス境界にサーキットブレーカーを実装してください。障害のあるサービスへの呼び出しを停止し、デグレードしたレスポンスを返します。
• Idempotency-Keyヘッダーを使用し、状態変更を行う全操作に冪等なエンドポイントを設計してください。
• デッドライン伝播によるリクエスト全体の時間上限を設けるため、積極的かつ現実的なタイムアウトを設定してください。

レート制限とAPIガバナンス

• APIゲートウェイでトークンバケットまたはスライディングウィンドウのレート制限を実施し、クライアントおよびエンドポイントごとに制限を設けてください。
• Retry-After、X-RateLimit-Limit、X-RateLimit-Remainingヘッダーとともに429を返してください。
• 内部サービスには専用の接続プールとスレッドプールを持つバルクヘッドパターンを使用してください。
• CI/CDパイプラインで自動リンティング（Spectral）を通じてAPI設計標準を強制してください。
• 仕様、所有者、SLAティア、廃止タイムラインを含む中央APIカタログを維持してください。

ページネーション、フィルタリング、クエリ設計

エンタープライズのデータ量では、効率的なクエリ設計は欠かせません。ページネーションのない/transactionsエンドポイントはいずれサービスをダウンさせます。

• 大規模データセットにはカーソルベースのページネーションを使用してください。オフセットベースのページネーションはスケールで劣化します。
• 次カーソル、総件数（コストが低い場合）、hasMoreブール値のページネーションメタデータを返してください。
• ペイロードサイズを削減するため、?fields=id,name,statusによるフィールドフィルタリングをサポートしてください。
• 複数フィールドの並び替えに対応するため、?sort=-createdAt,nameによる一貫したソートを実装してください。
• 複雑なクエリには構造化フィルター構文（?filter[status]=active&filter[amount][gte]=1000）を使用してください。

オブザーバビリティとAPIモニタリング

• すべてのエンドポイントにREDメトリクス（レート、エラー、レイテンシーパーセンタイル：p50、p95、p99）を計装してください。
• 全サービス呼び出しにわたって分散トレースID（W3C Trace Context）を伝播させてください。
• 相関ID、リクエストパス、レスポンスコード、レイテンシーを含む構造化JSONをログ出力してください。
• エラーだけでなくSLO違反にもアラートを設定してください。2%のエラー率は検索では許容範囲でも、決済では致命的になり得ます。
• レイテンシーヒートマップを含むクロスサービス依存関係ダッシュボードを構築してください。ベンガルールとコインバトールのチームはインシデント対応にこれらを活用しています。

実装チェックリスト

• コードを書く前にOpenAPI仕様を定義してください。コントラクトファーストの設計です。
• 初日から認証、レート制限、ルーティングを備えたAPIゲートウェイを導入してください。
• すべてのサービスにヘルスチェックエンドポイント（/health、/ready）を用意してください。
• 明確なエラーメッセージとともに、API境界でリクエストバリデーションを実施してください。
• CORSポリシーを明示的に設定してください。本番環境ではワイルドカードオリジンは使用しないでください。
• コンプライアンスのためにPIIをリダクションしたリクエスト/レスポンスのロギングを行ってください。
• 初回の本番デプロイ前にサービス間のコントラクトテストを実施してください。
• すべてのエンドポイントをサンプル、エラーコード、レート制限とともにドキュメント化してください。