API設計の基礎 ― REST/GraphQL/gRPC/WebSocket ― 生成AI時代のアーキテクチャ超入門

2023年にX（旧Twitter）が API v1.1 を実質即日有料化した際、Tweetbotなどの老舗サードパーティクライアントが一斉に停止した事件は、「APIは契約である」という事実を最も乱暴な形で示したケースとして業界に残っています。提供者側から見ても、バージョニング戦略や廃止予告ポリシーが甘いと、利用者の信用を一瞬で失います。

URLやパラメータの命名まで、公開した瞬間に後方互換の鎖がかかります。初期設計の質が長く尾を引きます。

主要4スタイル

API設計には大きく4つのスタイルがあります。どれが優れているかではなく、用途によって使い分けるもので、外部公開向けとマイクロサービス内部向けでは求められる特性が全く違います。

flowchart TB
    Q{用途は?} -->|外部公開Web API| REST[REST<br/>HTTP+JSON]
    Q -->|多様なクライアント<br/>過取得回避| GQL[GraphQL<br/>HTTP+クエリ言語]
    Q -->|マイクロサービス間<br/>内部高速通信| GRPC[gRPC<br/>HTTP/2+Protobuf]
    Q -->|双方向リアルタイム| WS[WebSocket<br/>TCP双方向]
    REST -.- E1[最も普及・<br/>キャッシュしやすい]
    GQL -.- E2[Facebook 2015〜<br/>BFFと相性◎]
    GRPC -.- E3[Google発<br/>低レイテンシ]
    WS -.- E4[チャット・通知・<br/>株価ストリーム]
    classDef question fill:#fef3c7,stroke:#d97706;
    classDef rest fill:#dbeafe,stroke:#2563eb;
    classDef gql fill:#fae8ff,stroke:#a21caf;
    classDef grpc fill:#dcfce7,stroke:#16a34a;
    classDef ws fill:#f0f9ff,stroke:#0369a1;
    class Q question;
    class REST rest;
    class GQL gql;
    class GRPC grpc;
    class WS ws;

スタイル	通信方式	代表用途
REST	HTTP + JSON	一般的なWeb API・外部公開
GraphQL	HTTP + クエリ言語	多様なクライアント向けAPI
gRPC	HTTP/2 + Protobuf	マイクロサービス間の内部通信
WebSocket	TCP双方向	リアルタイム通信

実際のプロジェクトでは「REST + 一部 WebSocket」のように複数を組み合わせるケースが多いです。

早期の判定フロー

詳細に入る前に、ユースケース別の第一候補を示します。まずこの表で当たりをつけてから、各方式の詳細を確認してください。

ユースケース	第一候補	次点
外部公開API（開発者向け）	REST	―
社内マイクロサービス間通信	gRPC	REST
Web・Mobileの両方から使う画面向けAPI	GraphQL or BFF + REST	REST
チャット・ゲーム・株価配信	WebSocket	Server-Sent Events
TypeScript単一スタック（Next.js等）	tRPC（型共有）	REST
公共・金融の既存資産と連携	REST or SOAP	gRPC

外部公開ならREST が既定値で、証明すべきはREST以外を選ぶ理由、という姿勢で十分です。

REST

REST（Representational State Transfer）は、HTTPの標準機能をそのまま使ったリソース指向のAPIスタイルです。URLでリソース（例：/users/123）を表し、操作はHTTPメソッド（GET・POST・PUT・DELETE）で表現します。シンプルで分かりやすく、外部公開APIの事実上の標準として最も広く普及しています。

HTTPの標準機能（キャッシュ・認証・ステータスコード）をそのまま活かせるため、CDNでの高速化やブラウザ対応がスムーズです。一方でクライアントが必要なデータを複数のエンドポイントから取得する必要があり、N+1問題（一覧取得の後に関連データを1件ずつ取得して大量のリクエストが飛ぶ現象）やオーバーフェッチ／アンダーフェッチが起きやすい弱点もあります。

代表的な設計	意味
GET `/users`	一覧取得
GET `/users/:id`	1件取得
POST `/users`	作成
PUT / PATCH `/users/:id`	更新
DELETE `/users/:id`	削除

外部公開APIなら迷わずRESTで、普及度と利用可能ツールの多さで他を圧倒します。

REST設計の原則

RESTを採用する場合、以下の原則を守ると長期的に運用しやすいAPIになります。単なる流儀ではなく、HTTPの思想に沿った設計のためのガイドラインです。

リソース指向で名詞を使う（/getUsers ではなく /users）
HTTPメソッドで操作を表現する（GET/POST/PUT/DELETE）
ステータスコードを正しく使う（200/201/400/401/404/500 など）
URLの階層で関連を表現する（/users/123/orders）
エラーレスポンスの形式を統一する（RFC 7807 Problem Details が定番）

GraphQL

GraphQL は2015年にFacebookが公開した、クライアントが欲しいデータの形を指定できるクエリ言語です。RESTのように固定されたエンドポイントではなく、単一のエンドポイント（通常 /graphql）に対して「この画面にはこのフィールドだけ欲しい」とクエリを投げます。

Webとモバイル、内部ダッシュボードなど複数のクライアントが異なるデータ形を必要とする場面で威力を発揮します。一方、HTTPキャッシュが効きにくく、N+1問題は自力で解決する必要があり、サーバ側の実装難度はRESTより高くなります。

強み	弱み
必要なデータだけ取得できる	キャッシュ戦略が複雑
型スキーマで自動ドキュメント生成	N+1 は自力で解決が必要
モバイルの帯域節約に効く	学習コストが高い
フロントエンドの開発体験が良い	サーバ側の実装難度が高い

多様なクライアント向けなら選択肢に入ります。シンプルなAPIにはオーバースペックです。

gRPC

gRPC はGoogleが開発した、Protocol Buffers（Protobuf）によるバイナリ通信のAPIフレームワークです。HTTP/2 上で動作し、双方向ストリーミングにも対応しているため、大量のリクエストを高速に捌けます。.proto ファイルからクライアント・サーバーのコードを複数言語で自動生成できるのも大きな強みです。

スキーマファーストで型が厳格に管理されるため、マイクロサービス間の内部通信では第一候補になります。ただしブラウザからの直接利用は困難（gRPC-Webが必要）で、HTTPツールでのデバッグもしにくいため、外部公開APIには向きません。

強み	弱み
圧倒的な性能（バイナリ通信）	ブラウザ直接利用が困難
言語横断でコード自動生成	デバッグしにくい
スキーマファーストで型安全	HTTPツール（curl等）で叩きにくい
HTTP/2でストリーミング対応	学習コストが中〜高

マイクロサービス間通信なら第一候補。外部公開には不向きです。

WebSocket

WebSocket は、クライアントとサーバー間で常時接続を維持し、双方向通信を行うプロトコルです。通常のHTTPリクエストは「クライアントが聞いて、サーバーが答える」の一往復ですが、WebSocketは「サーバーからクライアントへ能動的にメッセージを送れる」点が決定的に違います。

この性質から、リアルタイム性が求められる用途で使われます。チャット・株価表示・オンラインゲーム・ライブ配信・通知など、「サーバー側の状態変化を即座にクライアントに伝えたい」シーンではWebSocketが定番です。HTTP上でハンドシェイク後、独自プロトコルに昇格する仕組みになっています。

強み	弱み
低遅延・双方向通信	接続維持のリソース消費
サーバーからプッシュ可能	ロードバランサ・プロキシに配慮が必要
ブラウザ標準対応	再接続ロジックを自前で書く必要

REST では表現できないリアルタイム用途に特化しており、用途が合えば代替不可です。

4スタイルの比較

各スタイルは得意分野が明確に異なるため、単純な優劣比較は意味がありません。以下は典型的な用途での比較です。

観点	REST	GraphQL	gRPC	WebSocket
外部公開向き	◎	◯	×	△
ブラウザ対応	◎	◎	△	◎
性能	◯	◯	◎	◎
学習コスト	低	中	中	低
型安全	△	◎	◎	×
キャッシュ活用	◎	△	×	×

「外部公開REST / 内部gRPC / リアルタイムWebSocket」の使い分けが典型パターンです。

バージョニング戦略

API公開後は仕様変更が必ず発生するため、バージョン管理を最初から組み込む必要があります。バージョニングなしで運用すると、どんな小さな変更も利用者全員との調整が必要になり、「事実上APIを改良できなくなります」

方式	例	特徴
URLパス方式	`/api/v1/users`	最もシンプル・普及度◎
Acceptヘッダ方式	`Accept: application/vnd.api.v1+json`	URLが汚れない・学習コスト高
クエリパラメータ方式	`/api/users?version=1`	簡単・規模が大きくなると辛い

URLパス方式が最もシンプルで普及しています。「既定はこれ」と割り切って良いです。

API ライフサイクルの実務段階表

※ 2026年4月時点の業界相場値です。テクノロジー・人材市場の変化で陳腐化するため、定期的にアップデートが必要です。

APIは「公開したら契約」なので、公開前〜廃止までの段階を「数値で管理する」のが運用の肝です。

フェーズ	状態	サポート方針	移行猶予
Beta / Preview	実験的・仕様変更あり	SLA なし・破壊的変更あり得る	―
GA（General Availability）	安定版・本番利用可	後方互換維持	―
Deprecated（非推奨）	新規利用非推奨	継続動作・警告ヘッダ付与	最低6ヶ月〜2年
Sunset	廃止予告	動作継続・廃止日予告	最短3ヶ月
EOL（終了）	停止	動作しない	―

「Deprecation → Sunset → EOL の猶予は最低6ヶ月」が業界標準です。Google Cloud / AWS / Stripe などは2年以上の猶予を公式にコミットしており、これを守れないと利用者の信頼を失います。

Deprecationの猶予は最低6ヶ月、理想は2年。突然の廃止は信用を一瞬で失います。

認証方式

APIには必ず認証が必要です。用途に応じて以下の中から選びます。

方式	用途
Bearer Token（JWT（JSON Web Token、署名付きトークン）等）	SPA（Single Page Application、1ページで画面遷移するWebアプリ）・モバイル向けの最も一般的な方式
OAuth 2.0 / OIDC	外部サービス連携・SSO
API Key	サーバ間通信・B2B API
mTLS（相互TLS）	極めて高いセキュリティが必要な内部通信

外部公開ならOAuth 2.0、内部通信ならAPI Key や mTLS、BFF経由ならCookie + セッションが現実的です。

レート制限・エラー設計の数値Gate

※ 2026年4月時点の業界相場値です。テクノロジー・人材市場の変化で陳腐化するため、定期的にアップデートが必要です。

API 設計で「決めるべきこと」を曖昧なまま運用すると本番で事故るため、具体的な数値基準を最初に置きます。

設定項目	推奨値	理由
レート制限（公開API）	ユーザー毎 60req/分、IP毎 600req/分	ブルートフォース対策 + 公平性
レート制限（内部API）	10,000req/秒以上許容	内部利用は絞らない
タイムアウト	30秒（GET）/ 60秒（POST）	HTTPの慣例上限
ペイロード上限	1MB（REST）/ 10MB(ファイルアップロード)	DoS防止
バージョニング	URLパス方式（`/v1`）必須	最も普及・デバッグ容易
エラー形式	RFC 7807（Problem Details）	標準化されたエラー構造
廃止予告期間	最低6ヶ月、理想は2年	業界慣例

ステータスコードは「200（成功）/ 201（作成）/ 400（クライアントエラー）/ 401（未認証）/ 403（認可エラー）/ 404（存在しない）/ 409（競合）/ 429（レート超過）/ 500（サーバエラー）」を正しく使い分けます。「エラーを全部200で返す」は典型的な禁じ手で、クライアントがエラー処理できなくなります。

ケース別の選び方

公開Web API（外部開発者向け）

REST。普及度・ツール充実・学習コストで他を圧倒する。OpenAPIでドキュメント自動生成もできる。

多様なクライアント（Web・モバイル・IoT等）があるサービス

GraphQL。クライアントごとに欲しいデータが違う場合、RESTで複数エンドポイントを用意するよりもGraphQLが効率的。

マイクロサービス間の内部通信

gRPC。性能・型安全・コード自動生成の全てで有利。ブラウザ直接アクセスが無いためgRPCの弱点が影響しない。

チャット・通知・ゲーム等のリアルタイム機能

WebSocket。双方向通信が必須の用途では代替不可。

一般的なWebサービス + 一部リアルタイム

REST + WebSocketの併用。多くのサービスで採用されている組み合わせ。

API設計の鬼門・禁じ手

現場でよく見るAPI設計の失敗を、修正コストが大きい順に並べます。

禁じ手	なぜダメか
URLに動詞を入れる（`/getUsers` / `/deleteUser`）	HTTPメソッドと二重管理。`/users` + GET/DELETE が正解
エラーを全部 200 OKで返し body に `{success: false}`	クライアントのエラー処理が壊れる。HTTP標準ステータスコードを使う
バージョニングなしで公開	破壊的変更ができず APIが塩漬けに。`/v1` を最初から
認証を後付け	全エンドポイント修正が必要。最初から認証前提で設計
OpenAPI / Protobuf などのスキーマなし	仕様が口頭伝承になり、クライアントと実装がずれる
N+1クエリをAPIで発生させる	DB負荷が線形爆発。Includeパラメータや GraphQL で解決
ページネーションをOffset方式のみで提供	大量データで性能崩壊。Cursorベースも用意
破壊的変更を予告なく実施	利用者の信頼を一瞬で失う。X（旧Twitter）2023年のAPI v1.1有料化のパターン
冪等性の保証なしでPOSTリトライ許容	二重決済・在庫二重減算の原因。Idempotency-Keyヘッダで対応
レート制限なし	ボット・悪意ある利用で高額請求・DoS事故

Stripe のAPIは「壊さないAPI」の模範例として業界で知られています。2011年の初版から現在まで、10年以上にわたって同じエンドポイントが動き続けており、「後方互換性を維持しながら機能を追加する」という難題を解いた事例です。

API設計の鉄則は「壊さない、消さない、曖昧にしない」

AI時代の視点

AI駆動開発が前提になると、API設計は「スキーマファーストか」が決定的に重要になります。OpenAPI・GraphQL Schema・Protocol Buffers のような機械可読な定義ファイルがあれば、AIはクライアント・サーバー・テスト・ドキュメントまで一気通貫で生成できる。

逆にスキーマのない「なんとなくREST」では、AIは正確なコードを生成できず、ハルシネーションが頻発します。

AI時代に有利	AI時代に不利
OpenAPI / GraphQL / gRPC（スキーマファースト）	仕様書がExcel・Word・口頭
tRPC（TypeScript型共有）	型のない手書きREST
スキーマから自動生成（型・クライアント・docs）	手書きで型をクライアントに写す
標準的なRESTfulパターン	独自の命名・独自のエラー形式

型共有の観点では、フロント・バック両方TypeScriptならtRPCが最強です。APIスキーマを書く必要すらなく、型推論で全てが接続される。AIは型情報から意図を汲めるため、補完・生成の精度が劇的に高まります。

AI時代は「スキーマファースト+型共有」が圧勝で、口頭仕様のAPIは負債になります。

よくある勘違い

「GraphQLのほうが新しいから優れている」 → シンプルなCRUDアプリにGraphQLを採用すると、キャッシュ戦略やN+1対応で開発工数が逆に増える。「新しい＝優れている」は典型的な思考停止
「gRPCは性能が速いから内部通信は全部gRPC」 → HTTPデバッグツールが効かず、障害時の調査難度が跳ね上がります。内部でも小規模な連携ならRESTのほうが運用コストが低いケースは多い
「WebSocketはHTTPより速い」 → 接続維持のリソース消費と再接続ロジックのコストがあります。ポーリングで十分な用途にWebSocketを使うと、運用負荷が割に合わない
「バージョニングは後で考えれば良い」 → 後付けできません。初期設計で v1 を組み込まないと、破壊的変更ができずAPIが塩漬けになる

「ある日突然止まったAPI」（業界事例）

2023年にX（旧Twitter）がAPI v1.1 を実質終了して有料化した際、Tweetbot などの老舗サードパーティクライアントが一斉に停止した、という事例があります。利用者からすれば「API仕様＝永久に続く契約」のつもりで依存していたものが、ある日突然引き剥がされた事件でした。

当時、TweetbotがTwitter社の意向一つで一夜にして沈んでいく様子を見ていて、APIの契約性というものを生々しく感じた人も多かったはずです。この件は「APIは契約である」という事実を最も乱暴な形で示したケースとして知られています。

API設計の議論で「命名を後から変えられない」と言われる時、念頭にあるのはこうした事態です。

API公開は契約締結であり、廃止・変更のルールを最初から設計に組み込んでおきます。

決めるべきこと — あなたのプロジェクトでの答えは？

以下の項目について、あなたのプロジェクトの答えを1〜2文で言語化してみてください。曖昧なまま着手すると、必ず後から「なぜそう決めたんだっけ」が問われます。

APIスタイル（REST / GraphQL / gRPC / WebSocket / 組み合わせ）
認証方式（Bearer Token / OAuth / API Key / mTLS）
エラーレスポンス形式（RFC 7807 等）
バージョニング戦略（URLパス / Acceptヘッダ）
レート制限（ユーザー毎・IP毎・何req/分）
ドキュメント管理（OpenAPI / GraphQL Schema / Protobuf）
公開 or 内部のみの線引き

よくある失敗

RESTの命名が動詞だらけ ― /getUsers や /deleteUser のように、URLに動詞を含めるとHTTPメソッドと二重管理になる
GraphQLを闇雲に採用 ― シンプルなCRUDアプリにGraphQLを採用すると、キャッシュ戦略やN+1対応で開発工数が逆に増える
バージョニング無しで公開 ― 後から破壊的変更ができず、APIが塩漬けになる
認証を後付け ― 認証基盤を後から足そうとすると、全エンドポイントの修正が必要になる

最終的な判断の仕方

API設計は「一度公開したら壊せない契約」で、他のどの領域より後戻りコストが高い。命名・データ形式・エラー形式・バージョニング方針まで、外部に公開した瞬間に利用者が依存し、破壊的変更は実質不可能になります。

だから選定の核は「流行のスタイルを使いたいか」ではなく「利用者は誰か・用途は何か」に絞られる。外部開発者向けならREST一択、マイクロサービス間ならgRPC、多様なクライアントが必要ならGraphQL、リアルタイムならWebSocket。用途が決まれば答えはほぼ一意に決まります。

現代の決定的な軸は「スキーマファーストか」です。OpenAPI・Protobuf・GraphQL Schema・tRPCの型共有のように、機械可読な定義があればAIがクライアント・サーバー・テスト・ドキュメントを一気通貫で生成できる。

逆に「なんとなくREST」で型が口頭伝承だと、AIはハルシネーションを起こし、人間も仕様のズレに苦しみます。迷ったらREST + OpenAPIが最も安全な出発点で、必要が出てきたら内部通信だけgRPC、リアルタイム部分だけWebSocketを足すのが健全な育て方です。

選定の優先順位をまとめると次の通りです。

公開か内部かを最初に切り分ける（外部公開=REST、内部=gRPC候補）
利用者の形で決める（Web・モバイル・外部開発者・サービス間）
スキーマファーストを必須条件にする（OpenAPI / Protobuf / GraphQL）
逸脱理由がなければRESTに寄せる（普及度・ツール・AI精度で圧倒的有利）

「APIは契約、契約は壊せない」を肝に銘じ、初期設計は慎重に、スタイル選定は用途に忠実に行います。

まとめ

本記事はAPI設計について、4大スタイル・バージョニング・認証・レート制限の数値基準まで含めて解説しました。如何だったでしょうか。

外部公開はREST + OpenAPI、内部はgRPC、画面別はGraphQL、リアルタイムはWebSocket。スキーマファーストでAIに優しい設計に倒すのが現代の本命です。

次回は「フレームワーク」（Spring / Next.js / FastAPI / Rails 等）について解説します。

シリーズ目次に戻る → 『生成AI時代のアーキテクチャ超入門』の歩き方

それでは次の記事も閲覧いただけると幸いです。