本記事について
当サイトを閲覧いただきありがとうございます。 本記事はシリーズ『生成AI時代のアーキテクチャ超入門』の「ソフトウェアアーキテクチャ」カテゴリ第4弾として、API設計について解説する記事です。
「一度公開したAPIは契約書」命名・データ形式・エラー・認証方式まで、利用者が依存するため後から気軽に変えられません。本記事ではREST／GraphQL／gRPC／WebSocketの4大スタイルを比較し、用途別の使い分け・バージョニング戦略・認証方式・レート制限の数値基準まで解説します。
本記事のテーマについてさらに詳しく知りたい方は『システム設計のセオリーと実践方法がこれ1冊でしっかりわかる教科書』も参考にしてみてください。
そもそもAPIとは何か
APIとは、ざっくり言えば「ソフトウェア同士が会話するための窓口」です。
レストランのカウンターを想像してください。お客さん（フロントエンド）はメニュー表（APIドキュメント）を見て注文を出し、厨房（バックエンド）は注文通りの料理を決まった器（レスポンス形式）で返します。メニューにない注文は受け付けないし、器の形が突然変わったらお客さんは困る──この「注文の出し方と受け取り方のルール」がAPIです。Webアプリ、スマホアプリ、社内システム連携、AI呼び出しまで、現代のソフトウェアはAPIを通じて繋がっています。
なぜAPI設計が重要なのか
もしAPI設計を適当に済ませたらどうなるか。「とりあえず動くエンドポイント」を公開した瞬間、外部の利用者がその形に依存し始めます。URLやパラメータの命名、データ形式、エラーの返し方、認証方式まで、一度公開したAPIは契約書になるのです。破壊的変更は利用者全員に修正を強要するため、事実上できないと思っておくべきです。
2023年にX（旧Twitter）が API v1.1 を実質即日有料化した際、Tweetbotなどの老舗サードパーティクライアントが一斉に停止した事件は、「APIは契約である」という事実を最も乱暴な形で示したケースとして業界に残っています。提供者側から見ても、バージョニング戦略や廃止予告ポリシーが甘いと、利用者の信用を一瞬で失います。
URLやパラメータの命名まで、公開した瞬間に後方互換の鎖がかかります。初期設計の質が長く尾を引きます。
主要4スタイル
API設計には大きく4つのスタイルがあります。どれが優れているかではなく、用途によって使い分けるもので、外部公開向けとマイクロサービス内部向けでは求められる特性が全く違います。
| スタイル | 通信方式 | 代表用途 |
|---|---|---|
| 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 / 内部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等） | 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設計の失敗を、修正コストが大きい順に並べます。
| 禁じ手 | なぜダメか |
|---|---|
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事故 |
| 「GraphQLが新しいから優れている」前提で採用 | シンプルなCRUDにGraphQLはオーバースペック。キャッシュ・N+1対応で工数が逆に増える |
| 内部通信を全てgRPCで統一 | HTTPデバッグツールが効かず障害調査が困難に。小規模連携ならRESTの方が運用コストが低い |
Stripe のAPIは「壊さないAPI」の模範例として業界で知られています。2011年の初版から現在まで、10年以上にわたって同じエンドポイントが動き続けており、「後方互換性を維持しながら機能を追加する」という難題を解いた事例です。
API設計の鉄則は「壊さない、消さない、曖昧にしない」
AI判断軸
AI駆動開発が前提になると、API設計では「スキーマファーストか」が非常に重要になります。OpenAPI・GraphQL Schema・Protocol Buffers のような機械可読な定義ファイルがあれば、AIはクライアント・サーバー・テスト・ドキュメントまで一気通貫で生成できます。
| AI時代に有利 | AI時代に不利 |
|---|---|
| OpenAPI / GraphQL / gRPC（スキーマファースト） | 仕様書がExcel・Word・口頭 |
| tRPC（TypeScript型共有） | 型のない手書きREST |
| スキーマから自動生成（型・クライアント・docs） | 手書きで型をクライアントに写す |
| 標準的なRESTfulパターン | 独自の命名・独自のエラー形式 |
スキーマファーストがAI活用の前提条件になる理由
AIにAPIの実装を任せる場合、「何を作ればいいか」の定義が曖昧だと精度が落ちます。OpenAPIのYAMLやGraphQL Schemaがあれば、AIはその定義を正として実装コードを生成し、テストコードもスキーマとの整合性を検証する形で書けます。スキーマが存在しない場合、AIは既存のコードから推測して書くしかなく、暗黙のルール（エラーレスポンスの形式、ページネーションの方式等）を取りこぼします。
さらに、スキーマがあればAPIの変更管理もAIが支援できます。「このエンドポイントにフィールドを追加したい」と伝えれば、スキーマの変更 → サーバー実装の変更 → クライアント型の再生成 → テストの更新を一貫して行えます。
AIが生成したAPIの品質チェック
AIはCRUD的なエンドポイントを正確に書けますが、以下の点は人間が確認すべきです。
- バージョニング戦略 — パス（
/v2/users）かヘッダーか。AIは既存コードに合わせて出力するが、プロジェクト方針が未定義だと不整合が生じる - エラーレスポンスの一貫性 — RFC 7807（Problem Details）に従うか、独自形式か。AIは混在したまま書くことがある
- 認可チェックの漏れ — エンドポイントの権限チェックはAIが落としがちな箇所。スキーマに認可要件を注釈として書いておくと漏れを防げる
選定の優先順位
- 公開か内部かを最初に切り分ける（外部公開=REST、内部=gRPC/tRPC候補）
- 利用者の形で決める（Web・モバイル・外部開発者・サービス間）
- スキーマファーストを必須条件にする — AI活用の前提。OpenAPI / Protobuf / GraphQL
- 逸脱理由がなければRESTに寄せる（普及度・ツール・AI精度で圧倒的に有利）
「ある日突然止まった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 内部のみの線引き
この記事に関連する記事
まとめ
本記事はAPI設計について、4大スタイル・バージョニング・認証・レート制限の数値基準まで含めて解説しました。如何だったでしょうか。
外部公開はREST + OpenAPI、内部はgRPC、画面別はGraphQL、リアルタイムはWebSocket。スキーマファーストでAIに優しい設計に倒すのが現代の本命です。
次回は「フレームワーク」（Spring / Next.js / FastAPI / Rails 等）について解説します。
シリーズ目次に戻る → 『生成AI時代のアーキテクチャ超入門』の歩き方
本記事で扱った内容の詳細は OpenAPI Specification も合わせて参考にしてください。
それでは次の記事も閲覧いただけると幸いです。
📚 シリーズ：生成AI時代のアーキテクチャ超入門（21/89）