API設計の意思決定 — REST・GraphQL・gRPCをどう選ぶか

新しいサービスを作るたびに繰り返される議論があります。「APIはRESTでいく? GraphQL? それともgRPC?」——そしてこの議論は、しばしば「どれが優れているか」という不毛な方向に流れます。

結論から言えば、3つは競合ではなく、解いている問題が違います。RESTはリソースの公開、GraphQLはクライアント主導のデータ取得、gRPCはサービス間の高効率な手続き呼び出し。この記事では、それぞれの得意な構造と運用の実態、選定の判断基準、そして何を選んでも守るべき共通原則を整理します。

3スタイルの正体 — 何を抽象化しているか

REST — 「リソース」の公開

RESTはFieldingの博士論文で定義されたアーキテクチャ制約の集合で[1]、実務上は「HTTPの語彙(URL・メソッド・ステータスコード)でリソースを表現するAPI」として定着しています。

• 強み: HTTPそのものに乗ること。キャッシュ(CDN)、認証、リトライ、curl一発の検証、ブラウザとの親和性——Webのインフラ全部が味方になります
• 弱み: 画面が必要とするデータの形とリソースの形がずれると、取得の往復(N+1)や過剰取得が起きる。「注文と顧客と商品を1画面で」のために3回呼ぶ、あるいは巨大なレスポンスを返す

GraphQL — 「クエリ」の公開

GraphQLは、クライアントが必要なデータの形を宣言して問い合わせるクエリ言語と実行系です[2]。

• 強み: 画面ごとに最適な形でデータを1往復で取れる。多様なクライアント(Web・モバイル・パートナー)が同じグラフを別々の形で使う状況で真価が出る。スキーマが型付きの契約になる
• 弱み: サーバ側の複雑さを引き受ける。リゾルバのN+1対策(DataLoader等)、クエリの深さ・コスト制限、キャッシュ戦略(HTTPキャッシュが素直に効かない)、認可のフィールド単位の設計——「クライアントの自由」はサーバの規律で支払う

gRPC — 「手続き」の公開

gRPCは、Protocol BuffersでインターフェースをIDL(定義言語)として書き、HTTP/2上でバイナリ通信する RPC フレームワークです[3]。

• 強み: 性能と契約の厳格さ。バイナリ直列化は軽く、コード生成で型付きクライアントが全言語に配れる。双方向ストリーミングも標準装備。マイクロサービス間の内部通信の定番
• 弱み: ブラウザから直接呼びにくい(変換層が要る)、人間がcurlで叩けない、バイナリゆえデバッグに道具が要る。外部公開APIには不向きなことが多い

選定のデシジョンツリー

実務の選定は、技術の優劣ではなく「誰が呼ぶAPIか」でほぼ決まります。

1. 不特定の外部開発者に公開する → REST(+OpenAPIでスキーマ提供)。汎用性・学習コスト・エコシステムで他の選択肢がない
2. 社内サービス間の内部通信で、性能・型の厳格さが欲しい → gRPC。IDLファーストの開発はモジュール境界の規律とも相性がよい
3. 多様な画面・クライアントが、複雑に関連するデータを柔軟に取りたい → GraphQL。ただし専任でスキーマとサーバ規律を守れる体制があること
4. 迷ったら → REST。退屈な選択肢はたいてい正しく、後から部分的にGraphQL/gRPCを足す道も残る

アンチパターンは「1画面のためにGraphQL全面導入」「外部公開APIをgRPCだけで提供」「RESTと言いながら動詞だらけのRPC風URL」——いずれも、スタイルが解く問題と自分の問題のミスマッチです。

何を選んでも変わらない設計原則

スタイル選定より、こちらの方がAPIの寿命を決めます。

互換性はAPIの憲法

• 後方互換を壊さない: フィールドの削除・型変更・意味変更は破壊的変更。追加は安全、削除は移行計画つき
• バージョニング方針(URLの/v1/、ヘッダ、スキーマ進化)を最初に決め、「いつ消せるか」(非推奨→計測→削除の手順)まで含めて運用する
• gRPC/GraphQLはスキーマが契約なので、スキーマの差分チェックをCIに入れる(破壊的変更を機械検出する)。これはテスト戦略で書いたアーキテクチャテストのAPI版です

エラー設計は「機械が分岐でき、人間が調査できる」

• 機械可読なエラーコード(再試行してよいか、入力を直すべきか、を呼び出し側が分岐できる)
• 人間向けメッセージと、調査用の相関ID(trace_id)を必ず含める——オブザーバビリティとの接続点です
• 「なんでも200でbodyにerror」はHTTPのインフラ(監視・リトライ・キャッシュ)を全部敵に回します

一覧APIの三点セット

ページネーション(カーソル方式が既定)、フィルタ、ソート。あとから足すと互換性の問題になりやすい代表格なので、一覧を返すAPIには最初から設計しておきます。

レート制限と冪等性

公開APIにはレート制限と、その伝え方(429と再試行ヘッダ)。課金・注文のような操作には冪等キー(同じリクエストの再送が二重実行にならない仕組み)。障害時のリトライを安全にする、地味で決定的な設計です。

まとめ

• REST・GraphQL・gRPCは競合ではない。リソース公開/クライアント主導の取得/内部の高効率RPCという別の問題を解いている
• 選定は「誰が呼ぶか」で決まる: 外部公開はREST、内部通信はgRPC、多様なクライアント×複雑なデータはGraphQL、迷ったらREST
• GraphQLの柔軟さはサーバ側の規律(N+1・コスト制限・フィールド認可)で支払う。体制ごと導入する
• スタイルより寿命を決めるのは共通原則: 後方互換・エラー設計・ページネーション・冪等性。スキーマ差分チェックをCIに入れる

APIは一度公開したら、呼び出し側のコードという「他人の資産」に組み込まれます。設計の良し悪しが自分のチームの外に複利で効いていく——だからこそAPI設計は、技術選定ではなく約束の設計として扱う価値があります。