API設計 | octomblog

API（Application Programming Interface）設計とは、システム間の通信インターフェースを定義する活動であり、その品質はシステムの使いやすさ・変更しやすさ・安全性に直結する。RESTful API はリソース指向の設計原則に基づき、HTTP メソッド（GET・POST・PUT・PATCH・DELETE）を適切に使い分けることで、操作の意味論（semantics）を明確にする。URL はリソースを表す名詞であるべきであり、動詞を含めることはアンチパターンとされる（例: /api/getUser より /api/users/{id}）。

GraphQL はクライアントが必要なフィールドを宣言的に指定できる柔軟性を持つ反面、N+1問題（クエリのルートフィールド解決時に子フィールドごとに個別クエリが発行される問題）が生じやすい。DataLoader パターンによるバッチ処理と Persisted Queries が主な対策となる。gRPC は Protocol Buffers によるスキーマ定義と高効率なバイナリシリアライズを用い、サービス間通信（特にマイクロサービス内部）での低遅延・型安全な通信に適している。双方向ストリーミングもサポートしており、リアルタイム性の高いユースケースにも対応できる。

べき等性（Idempotency）は API 設計の重要な概念で、同一リクエストを複数回送信しても結果が変わらない特性を指す。GET・HEAD・PUT・DELETE は冪等であるべきで、POST はデフォルトでは冪等でない。決済や注文などの重要な POST 操作には Idempotency-Key ヘッダーを用いて冪等性を保証する設計が推奨される。APIバージョニングは URI パス（/v1/）・クエリパラメータ・HTTP ヘッダーの各方式があり、クライアントへの破壊的変更（breaking change）を制御するための重要な手段である。

コードレビューで着目するポイント

HTTP メソッドの使い分けが意味論的に正しいか（副作用のある操作に GET を使っていないか）
URL が名詞（リソース）ベースで設計されているか
べき等性の保証が必要な操作（決済・注文登録など）に冪等キーの仕組みが実装されているか
GraphQL の N+1 問題に対して DataLoader 等のバッチ処理が適用されているか
API のレスポンスにエラーコードと人間可読なメッセージが含まれているか
APIバージョニング戦略が明確で、破壊的変更と後方互換変更の区別ができているか
gRPC の .proto ファイルがバージョン管理され、フィールド番号の変更が行われていないか

典型的なアンチパターン

RPC スタイルの URL 混入: REST API のつもりで /api/activateUser や /api/sendEmail のような動詞URLを使ってしまうパターン。リソース指向の設計原則と相反し、HTTPメソッドの意味論が活かせない。

過剰なグローバルGraphQLスキーマ: 全エンティティを単一の GraphQL スキーマに詰め込み、Bounded Context を跨いだ resolver が連鎖する設計。パフォーマンス問題とスキーマの肥大化を引き起こす。

バージョニングなしの破壊的変更: APIのレスポンス構造を変更したり必須フィールドを追加したりする際に、既存クライアントへの影響を無視してデプロイするパターン。利用者が多い API ではサービス断の原因となる。

参考リソース

『RESTful Web API』Leonard Richardson（O’Reilly）
『Production Ready GraphQL』Marc-Andre Giroux（https://productionreadygraphql.com/）
gRPC 公式ドキュメント（https://grpc.io/docs/）
Stripe API 設計（ベストプラクティスの参考例: https://stripe.com/docs/api）
OpenAPI Specification（https://spec.openapis.org/）