ガイド
REST vs GraphQL vs gRPC — API設計の選び方
APIの設計スタイルはシステムの性能・開発体験・保守性に直結します。REST・GraphQL・gRPCそれぞれの特性を理解し、ユースケースに応じた適切な選択ができるようになりましょう。
3方式の概要比較
| 観点 | REST | GraphQL | gRPC |
|---|---|---|---|
| プロトコル | HTTP/1.1（HTTPS） | HTTP/1.1（HTTPS） | HTTP/2 |
| データ形式 | JSON（主流） | JSON | Protocol Buffers（バイナリ） |
| スキーマ | OpenAPI/Swagger（任意） | GraphQL Schema（必須） | Protobuf（必須） |
| 型安全性 | 低（OpenAPIで向上可） | 高（型定義が必須） | 最高（コンパイル時チェック） |
| パフォーマンス | 中 | 中（複雑クエリで低下） | 最高（バイナリ・HTTP/2多重化） |
| 学習コスト | 低（業界標準） | 中（クエリ言語・Resolver） | 高（Protobuf・コード生成） |
| キャッシュ | 容易（HTTPキャッシュ） | 困難（POST多用のため） | 独自実装が必要 |
| ブラウザ対応 | ◎ネイティブ | ◎ライブラリ経由 | △gRPC-Webが必要 |
各方式の詳細
REST（Representational State Transfer）
URLでリソースを表し、HTTPメソッド（GET/POST/PUT/DELETE）で操作するスタイル。業界標準として最も普及しており、ツール・ライブラリ・ドキュメントが豊富です。
向いているケース
- ·外部公開API（パートナー・サードパーティ）
- ·モバイル/Webフロントエンドとの通信
- ·チームのHTTP知識が深い
- ·HTTPキャッシュを最大活用したい
弱点
- ·Over-fetching（不要なフィールドも取得）
- ·Under-fetching（複数APIを呼ぶ必要あり）
- ·エンドポイント数が増えると管理が大変
- ·バージョン管理（v1/v2）が複雑化
GraphQL
クライアントが必要なデータを自由に指定できるクエリ言語。Facebook（Meta）が開発。1つのエンドポイントで柔軟なデータ取得が可能で、フロントエンド開発の体験を大幅に向上させます。
向いているケース
- ·複数のフロントエンドが同一APIを使う（Web/iOS/Android）
- ·データ取得効率化が重要（BFF代替）
- ·複雑な関連データをまとめて取得
- ·型安全な開発体験を重視
弱点
- ·N+1問題（DataLoaderで対策が必要）
- ·HTTPキャッシュが効かない
- ·複雑なクエリでサーバー負荷増大
- ·Resolver設計の学習コストが高い
gRPC（Google Remote Procedure Call）
Protocol Buffersでインターフェースを定義し、バイナリ通信するRPCフレームワーク。HTTP/2の多重化・ストリーミングにより、マイクロサービス間通信で最高のパフォーマンスを発揮します。
向いているケース
- ·マイクロサービス間の内部通信
- ·低レイテンシ・高スループットが必要
- ·双方向ストリーミング（チャット・リアルタイム処理）
- ·PolyglotサービスのAPI契約管理
弱点
- ·ブラウザから直接呼び出せない（gRPC-Web必要）
- ·Protobufのバイナリはデバッグしにくい
- ·Protobuf + コード生成の学習コスト
- ·外部公開APIには不向き
選択のフレームワーク
外部パートナーや一般公開するAPIREST — 業界標準・ドキュメント化しやすい
Webフロント/モバイル複数がデータを柔軟に取得したいGraphQL — over/under-fetchingを解決
マイクロサービス間の内部APIgRPC — 最高性能・型安全な契約
リアルタイム・ストリーミング処理gRPC（双方向ストリーム）またはWebSocket
チームのスキル・既存スタックを優先学習コストを考慮：REST > GraphQL > gRPC
同一システムで複数を使っていい？外部公開はREST、内部はgRPC、BFFにGraphQL — 混在は一般的
API設計のベストプラクティス
▸
スキーマファーストで設計する: 実装前にOpenAPI/Protobuf/GraphQL Schemaを定義する。フロントエンドとバックエンドが並行開発できる。変更の影響範囲も早期に把握できる。
▸
バージョニング戦略を事前に決める: REST: URLパス（/v1/）が最も一般的。Headerベース（Accept: application/vnd.api+json; version=2）も有力。GraphQLは非推奨フィールドで段階廃止。gRPCはprotobufのフィールド番号で後方互換を保つ。
▸
エラーレスポンスを統一する: RFC 7807（Problem Details）等の標準フォーマットに合わせる。エラーコード・メッセージ・詳細・トレースIDを含める。クライアントがプログラム的に処理できる形式にする。
▸
レート制限・認証を最初から設計する: 「後でつける」は難しい。認証（JWT Bearer / API Key）・レート制限（429 Too Many Requests）・ページネーション方式をAPIファーストで決める。