本記事について
当サイトを閲覧いただきありがとうございます。 本記事はシリーズ『生成AI時代のアーキテクチャ超入門』の「ソフトウェアアーキテクチャ」カテゴリ第4弾として、API設計について解説する記事です。
「一度公開したAPIは契約書」──命名・データ形式・エラー・認証方式まで、利用者が依存するため後から気軽に変えられません。本記事ではREST／GraphQL／gRPC／WebSocketの4大スタイルを比較し、用途別の使い分け・バージョニング戦略・レート制限の数値基準まで解説します。
本記事のテーマについてさらに詳しく知りたい方は『システム設計のセオリーと実践方法がこれ1冊でしっかりわかる教科書』も参考にしてみてください。
この記事の結論
- 外部公開はREST+OpenAPI、内部高速通信はgRPC、画面特化はGraphQL、リアルタイムはWebSocket
- スキーマファーストで設計し、AIに渡せる形にする
- バージョニング（/v1）とレート制限は最初から決める
- 廃止の猶予は最低6ヶ月。突然の変更は信用を一瞬で失う
この記事を読む前に
本記事はプログラムやAPIといった開発寄りの話が中心です。IT用語にあまり馴染みがない方は、基礎編の「プログラムとAPIの基本」を先に読んでおくと格段に分かりやすくなると思います。また、読んでいて分からない用語が出てきたときは用語集で調べながら読み進められます。
そもそもAPIとは何か
APIとは、ざっくり言えば「ソフトウェア同士が会話するための窓口」です。
レストランのカウンターを想像してください。お客さん（フロントエンド）はメニュー表（APIドキュメント）を見て注文を出し、厨房（バックエンド）は注文通りの料理を決まった器（レスポンス形式）で返します。メニューにない注文は受け付けないし、器の形が突然変わったらお客さんは困る──この「注文の出し方と受け取り方のルール」がAPIです。
なぜAPI設計が重要なのか
もしAPI設計を適当に済ませたらどうなるか。「とりあえず動くエンドポイント」を公開した瞬間、外部の利用者がその形に依存し始めます。URLやパラメータの命名、データ形式、エラーの返し方まで、一度公開したAPIは契約書になります。破壊的変更は利用者全員に修正を強要するため、事実上できないと思っておくべきです。
2023年にX（旧Twitter）がAPI v1.1を実質即日有料化した際、Tweetbotなどの老舗サードパーティクライアントが一斉に停止した事件は、「APIは契約である」という事実を最も乱暴な形で示したケースとして業界に残っています。
主要4スタイル
API設計には大きく4つのスタイルがあります。どれが優れているかではなく、用途によって使い分けるものです。
| スタイル | 通信方式 | 代表用途 |
|---|---|---|
| REST | HTTP+JSON | 一般的なWeb API・外部公開 |
| GraphQL | HTTP+クエリ言語 | 多様なクライアント向けAPI |
| gRPC | HTTP/2+Protobuf | マイクロサービス間の内部通信 |
| WebSocket | TCP双方向 | リアルタイム通信 |
REST ― 外部公開の事実上の標準
RESTは、URLでリソース（/users/123）を表し、操作をHTTPメソッド（GET・POST・PUT・DELETE）で表現するリソース指向のスタイルです。HTTPの標準機能（キャッシュ・認証・ステータスコード）をそのまま活かせるため、CDN高速化やブラウザ対応がスムーズで、普及度とツールの充実で他を圧倒します。弱点は、クライアントが複数エンドポイントからデータをかき集める必要があり、N+1問題やオーバーフェッチが起きやすいことです。
設計原則はシンプルです。URLは名詞（/getUsers ではなく /users）、操作はHTTPメソッド、関連はURL階層（/users/123/orders）で表現し、ステータスコードを正しく使い、エラー形式はRFC 7807（Problem Details）で統一します。
GraphQL ― 多様なクライアントの画面特化
GraphQLは、単一エンドポイントに「この画面にはこのフィールドだけ欲しい」とクエリを投げられる、Facebook発のクエリ言語です。Webとモバイルで欲しいデータ形が違う場面で威力を発揮し、型スキーマからドキュメントも自動生成できます。一方、HTTPキャッシュが効きにくく、N+1問題は自力で解決する必要があり、サーバ側の実装難度はRESTより高い。シンプルなCRUDにはオーバースペックです。
gRPC ― マイクロサービス内部通信の第一候補
gRPCは、Protocol Buffersによるバイナリ通信のフレームワークです。HTTP/2上で双方向ストリーミングに対応し、大量リクエストを高速に捌け、.proto ファイルから多言語のコードを自動生成できます。スキーマファーストで型が厳格なため内部通信の第一候補ですが、ブラウザからの直接利用が困難でHTTPツールでのデバッグもしにくいため、外部公開には向きません。
WebSocket ― リアルタイム用途では代替不可
WebSocketは、常時接続を維持して「サーバーからクライアントへ能動的にメッセージを送れる」プロトコルです。チャット・株価配信・オンラインゲーム・通知など、サーバー側の状態変化を即座に伝えたい用途の定番で、この性質が必要なら代替はありません。代償として接続維持のリソース消費と、再接続ロジックの自前実装が必要になります。
4スタイルの比較
どう選べばいいのか
判断はシンプルで、まず「公開か内部か」で切り分けます。外部公開API（開発者向け）はRESTが既定値で、証明すべきは「REST以外を選ぶ理由」のほうです。社内マイクロサービス間通信はgRPCが第一候補。Web・モバイル両対応の画面向けAPIはGraphQLかBFF+REST。チャット・ゲーム・配信はWebSocket。そしてNext.js等のTypeScript単一スタックなら、型をそのまま共有できるtRPCが候補に入ります。実際のプロジェクトでは「REST+一部WebSocket」のように組み合わせるのが普通です。
公開後の運用ルールも最初に決めます。バージョニングはURLパス方式（/api/v1/users）が最もシンプルで普及しており、既定はこれと割り切ってよいです。認証は外部公開ならOAuth 2.0 / OIDC、サーバ間・B2BならAPI Key、BFF経由ならCookie+セッションが現実的です。そしてAPIのライフサイクルは「Beta → GA → Deprecated → Sunset → EOL」の段階で管理し、Deprecationの移行猶予は最低6ヶ月、理想は2年が業界標準です。Google Cloud・AWS・Stripeは2年以上の猶予を公式にコミットしています。
レート制限・エラー設計の数値Gate
※ 2026年4月時点の業界相場値です。
曖昧なまま運用すると本番で事故るため、具体的な数値基準を最初に置きます。
| 設定項目 | 推奨値 |
|---|---|
| レート制限（公開API） | ユーザー毎 60req/分、IP毎 600req/分 |
| タイムアウト | 30秒（GET）/ 60秒（POST） |
| ペイロード上限 | 1MB（REST）/ 10MB（ファイルアップロード） |
| バージョニング | URLパス方式（/v1）必須 |
| エラー形式 | RFC 7807（Problem Details） |
| 廃止予告期間 | 最低6ヶ月、理想は2年 |
ステータスコードは200 / 201 / 400 / 401 / 403 / 404 / 409 / 429 / 500を正しく使い分けます。「エラーを全部200で返す」は典型的な禁じ手で、クライアントがエラー処理できなくなります。
3つのシナリオで考える
個人開発・スタートアップの場合
TypeScriptの単一スタックであれば、tRPC（またはNext.jsのServer Actions）で型をそのまま共有するのが最速だと思います。外部に公開する段になってからRESTを足せば問題ありません。GraphQLも魅力的に見えますが、1人開発ではスキーマ管理の手間が利益を上回ってしまうのが正直なところです。
中小SaaSの場合
外部公開はREST（OpenAPI）、社内のサービス間はgRPC、という使い分けが定石です。OpenAPIのYAMLをGitで管理してSDK・ドキュメント・モックを自動生成しつつ、レート制限やエラー形式（RFC 7807）、バージョニングといった数値Gateは公開前に固めておきたいところです。
大企業の場合
この規模になるとAPI仕様の全社標準化が本題になります。命名規約・認証方式（OAuth 2.0 / OIDC）・Deprecation期間（最低6ヶ月、理想は2年）を全社ガイドラインとして定めて、API Gatewayで一元管理します。部署ごとにバラバラの流儀で公開されたAPIは、後の統合時に地獄を生んでしまうのです。
AI判断軸 ― スキーマファーストが前提条件
AI駆動開発が前提になると、API設計では「スキーマファーストか」が非常に重要になります。
スキーマがAIの正解定義になる
AIにAPIの実装を任せる場合、OpenAPIのYAMLやGraphQL Schema・Protobufがあれば、AIはその定義を正として実装コード・テスト・ドキュメントまで一気通貫で生成できます。スキーマが存在しない場合、AIは既存コードから推測して書くしかなく、暗黙のルール（エラーレスポンスの形式、ページネーションの方式等）を取りこぼします。さらにスキーマがあれば変更管理も支援でき、「このエンドポイントにフィールドを追加したい」と伝えるだけで、スキーマ変更→サーバー実装→クライアント型の再生成→テスト更新を一貫して行えます。
AIが生成したAPIの品質チェック
AIはCRUD的なエンドポイントを正確に書けますが、バージョニング戦略（プロジェクト方針が未定義だと不整合を起こす）、エラーレスポンスの一貫性（混在したまま書くことがある）、そして認可チェックの漏れ（AIが最も落としがちな箇所）は人間が確認すべきです。スキーマに認可要件を注釈として書いておくと漏れを防げます。
やってはいけないこと
現場でよく見るAPI設計の失敗を、修正コストが大きい順に6つに絞ります。
| 禁じ手 | なぜダメか → どうするか |
|---|---|
| バージョニングなしで公開 | 破壊的変更ができずAPIが塩漬けになる → /v1 を最初から付ける |
| エラーを全部200 OKで返す | クライアントのエラー処理が壊れる → HTTP標準ステータスコードを使う |
URLに動詞を入れる（/getUsers） | HTTPメソッドと二重管理になる → /users+GET/DELETEにする |
| スキーマ（OpenAPI / Protobuf）なし | 仕様が口頭伝承になりクライアントと実装がずれる → スキーマファーストにする |
| 冪等性の保証なしでPOSTリトライを許容 | 二重決済・在庫二重減算の原因になる → Idempotency-Keyヘッダで対応する |
| レート制限なしで公開 | ボット・悪用で高額請求・DoS事故になる → 数値Gateを最初に設定する |
対照的に、StripeのAPIは「壊さないAPI」の模範例として知られています。2011年の初版から10年以上同じエンドポイントが動き続けており、後方互換を維持しながら機能を追加するという難題を解いた事例です。API設計の鉄則は「壊さない、消さない、曖昧にしない」です。
筆者メモ ― 「ある日突然止まったAPI」
2023年にX（旧Twitter）がAPI v1.1を実質終了して有料化した際、Tweetbotなどの老舗サードパーティクライアントが一斉に停止しました。利用者からすれば「API仕様＝永久に続く契約」のつもりで依存していたものが、ある日突然引き剥がされた事件です。TweetbotがTwitter社の意向一つで一夜にして沈んでいく様子に、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）
言語化した答えはADRとして残します。書き方の具体例は以下の記事で解説しています。
この記事に関連する記事
まとめ
本記事はAPI設計について、4大スタイル・バージョニング・認証・レート制限の数値基準まで含めて解説しました。如何だったでしょうか。
外部公開はREST+OpenAPI、内部はgRPC、画面別はGraphQL、リアルタイムはWebSocket。スキーマファーストでAIに優しい設計に倒すのが現代の本命です。
次回は「フレームワーク」（Spring / Next.js / FastAPI / Rails等）について解説します。
シリーズ目次に戻る → 『生成AI時代のアーキテクチャ超入門』の歩き方
本記事で扱った内容の詳細は OpenAPI Specification も合わせて参考にしてください。
それでは次の記事も閲覧いただけると幸いです。
📚 シリーズ：生成AI時代のアーキテクチャ超入門（27/95）