API設計とAPIゲートウェイ

約10分

本番AIサービスのAPI設計を学びたいエンジニア、マイクロサービスの通信方式を理解したい方

クラウドアーキテクチャ入門の全体構成を把握していると理解が深まります

API（Application Programming Interface）とは、異なるソフトウェアコンポーネント間の通信契約です。クライアント（ブラウザ、モバイルアプリ、他サービス）は何を送れば何が返ってくるかをAPIの仕様から知り、サーバー内部の実装を知らなくても呼び出せます。本番AIサービスでは、複数のマイクロサービスが連携するため、API設計と統一的な入口となるAPIゲートウェイが不可欠です。

API設計の3方式: REST・GraphQL・gRPC

現代のWebサービスで広く使われるAPI方式は3種類あります。それぞれ異なる問題を解決するために生まれました。

REST API

REST（Representational State Transfer）とは、HTTPの仕組みをそのまま活用したAPI設計スタイルです。「リソース」を中心に設計し、HTTPメソッドで操作を表現します。

HTTPメソッド	意味	例
`GET`	取得	`GET /users/123` → ユーザー123を取得
`POST`	作成	`POST /conversations` → 新しい会話を作成
`PUT`	全体更新	`PUT /users/123` → ユーザー123を全フィールド更新
`PATCH`	部分更新	`PATCH /users/123` → ユーザー123の一部フィールドを更新
`DELETE`	削除	`DELETE /conversations/456` → 会話456を削除

レスポンスはHTTPステータスコードで状態を伝えます。

200 OK           → 成功（取得・更新）
201 Created      → 作成成功
400 Bad Request  → クライアントのリクエストに問題あり
401 Unauthorized → 認証が必要
403 Forbidden    → 認証済みだがアクセス権限なし
404 Not Found    → リソースが存在しない
429 Too Many Requests → レート制限に達した
500 Internal Server Error → サーバー側のエラー

GraphQL

GraphQLとは、Facebookが開発したクエリ言語ベースのAPI仕様です。単一のエンドポイント（/graphql）に対してクライアントが「必要なフィールドだけ」をクエリで指定して取得します。

# クライアントが必要なフィールドだけ指定できる
query {
  user(id: "123") {
    name
    email
    conversations(last: 5) {
      id
      createdAt
      messages(last: 1) {
        content
      }
    }
  }
}

REST では複数エンドポイントを叩いてデータを結合する必要がある場面で、GraphQL は1回のリクエストで必要なデータをまとめて取得できます。

gRPC

gRPC（Google Remote Procedure Call）とは、Googleが開発したバイナリプロトコルベースのRPCフレームワークです。Protocol Buffers（.proto ファイル）でインターフェースを型付き定義し、JSONではなくバイナリで通信します。

// chat.proto
service ChatService {
  rpc SendMessage (MessageRequest) returns (MessageResponse);
  rpc StreamResponse (MessageRequest) returns (stream MessageChunk);
}

message MessageRequest {
  string conversation_id = 1;
  string content = 2;
}

比較表: REST vs GraphQL vs gRPC

項目	REST	GraphQL	gRPC
プロトコル	HTTP/JSON	HTTP/JSON	HTTP/2 + Protocol Buffers（バイナリ）
エンドポイント	複数（リソースごと）	単一（`/graphql`）	メソッドごと
型定義	OpenAPI（任意）	スキーマ必須	.proto ファイル必須
主な用途	公開API、シンプルなCRUD	フロントエンド向け複雑データ取得	マイクロサービス間通信
学習コスト	低	中	中〜高
ブラウザ対応	ネイティブ	ネイティブ	限定的（grpc-web が必要）
パフォーマンス	標準	標準	高速（バイナリ通信）

APIゲートウェイとは何か

APIゲートウェイ（API Gateway）とは、すべてのクライアントからのリクエストを受け取る単一の入口となるコンポーネントです。複数のバックエンドサービスを直接クライアントに公開する代わりに、APIゲートウェイが一元的に処理を担当します。

APIゲートウェイのアーキテクチャ

graph TD
    Browser["ブラウザ"] --> GW["APIゲートウェイ"]
    Mobile["モバイルアプリ"] --> GW
    External["外部サービス"] --> GW

    GW --> AuthCheck["① 認証チェック\nJWT検証 / APIキー確認"]
    AuthCheck --> RateLimit["② レート制限チェック\nRedisでカウント管理"]
    RateLimit --> Route["③ ルーティング\nパスに応じて転送先決定"]

    Route --> UserSvc["ユーザーサービス\n:8001"]
    Route --> AISvc["AIチャットサービス\n:8002"]
    Route --> FileSvc["ファイルサービス\n:8003"]

    GW --> Log["④ ログ・メトリクス収集\nDatadog / CloudWatch"]

    UserSvc --> DB["PostgreSQL"]
    AISvc --> LLMAPI["LLM API\nAnthropic / OpenAI"]
    FileSvc --> Storage["オブジェクトストレージ\nS3 / GCS"]

APIゲートウェイが担う6つの責務

1. 単一エントリーポイント

クライアントはAPIゲートウェイのURLだけを知れば、背後に何十ものマイクロサービスがあっても意識しなくて済みます。バックエンドのサービス構成を変更しても、クライアント側のコードは変わりません。

2. 認証・認可

すべてのリクエストに対してJWTトークンの検証やAPIキーの確認を行います。有効でないリクエストは各バックエンドサービスに到達する前に弾きます。

リクエストヘッダー例:
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
X-API-Key: sk-proj-xxxxxxxxxxxxx

3. レート制限

1ユーザーあたり・IPアドレスあたりのリクエスト数を制限し、バックエンドサービスの過負荷やAPIの悪用を防ぎます。

4. リクエストルーティング

リクエストのパス（/api/chat/* → AIサービス、/api/users/* → ユーザーサービス）に応じて転送先を決定します。

5. SSL終端

クライアントとAPIゲートウェイ間はHTTPS（暗号化）、ゲートウェイとバックエンドサービス間は内部ネットワーク内のHTTPにする構成を「SSL終端」といいます。証明書管理をゲートウェイに集約できます。

6. ログとメトリクス収集

すべてのAPIリクエストのログを一か所で収集できます。レイテンシ、エラー率、スループットを監視ツールに送信します。

レート制限の3つのアルゴリズム

レート制限（Rate Limiting）とは、単位時間あたりのリクエスト数を制御する仕組みです。バックエンドサービスの過負荷保護とAPIの不正利用防止が目的です。

アルゴリズム	仕組み	特徴
固定ウィンドウ	1分ごとにカウンターをリセット	実装シンプル。ウィンドウ境界でバーストが発生しやすい
スライディングウィンドウ	直近N秒のリクエスト数を追跡	バーストを防ぎやすい。実装やや複雑
トークンバケット	一定レートでトークンを補充。リクエスト時にトークンを消費	バーストを一定量許可しつつ平均レートを制限できる

AWS API GatewayやKongなど主要なゲートウェイはこれらのアルゴリズムを内蔵しています。

APIバージョニング

APIの仕様を変更する際、既存クライアントを壊さないようにバージョン管理が必要です。

URLバージョニング（最も一般的）

https://api.example.com/v1/chat
https://api.example.com/v2/chat

URLに含まれるため視覚的に分かりやすく、キャッシュが効きやすいメリットがあります。

ヘッダーバージョニング

GET /chat
Accept: application/vnd.api+json; version=2

URLを汚さない設計ですが、実装と試験が複雑になります。

実運用ではURLバージョニングが最も広く使われます。v1が廃止される前に、十分な移行期間を設けて告知します。

AI API特有の設計

LLM APIを使うAIサービスでは、一般的なREST APIとは異なる設計上の考慮点があります。

ストリーミングレスポンス（SSE）

LLMの生成は数秒〜数十秒かかります。生成完了まで待ってからレスポンスを返すと、ユーザーには長い無応答時間が生じます。Server-Sent Events（SSE） を使うと、生成中のテキストを順次クライアントに送信できます。

# FastAPI でのSSEストリーミング例
from fastapi.responses import StreamingResponse

async def stream_chat(message: str):
    async def generate():
        async with anthropic_client.messages.stream(
            model="claude-opus-4-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": message}]
        ) as stream:
            async for text in stream.text_stream:
                yield f"data: {text}\n\n"
    return StreamingResponse(generate(), media_type="text/event-stream")

コストパーコール追跡

LLM APIはトークン数に応じた従量課金です。各APIリクエストの入力トークン数・出力トークン数・コストをDBに記録します。

{
  "request_id": "req_123",
  "user_id": "user_456",
  "model": "claude-opus-4-5",
  "input_tokens": 250,
  "output_tokens": 1800,
  "cost_usd": 0.0234,
  "latency_ms": 4200
}

主要なAPIゲートウェイ製品

製品	種別	特徴
AWS API Gateway	マネージド	AWSサービスとの統合が容易。Lambda、ECSと組み合わせやすい
Kong	OSS/マネージド	豊富なプラグインエコシステム。オンプレでも使える
Nginx	OSS	高性能リバースプロキシ。カスタマイズ性が高い
Cloudflare Workers	エッジ	エッジで動作。グローバルなレイテンシ最小化に向く
Traefik	OSS	Kubernetes環境との親和性が高い

まとめ

REST は HTTP を活用したシンプルな設計で、公開APIや CRUD 操作に最適
GraphQL は必要なフィールドだけ取得でき、複雑なフロントエンドデータ取得に向く
gRPC はバイナリ通信で高速、型付きスキーマが必須で、マイクロサービス間通信に向く
APIゲートウェイは認証・レート制限・ルーティング・ログ収集を一元化する単一入口
AIサービスではストリーミングレスポンス（SSE）とコスト追跡が追加の設計ポイント

よくある質問

Q: 小規模プロジェクトでもAPIゲートウェイは必要ですか？

A: サービスが単一の場合は不要なことが多いです。ただし、認証・レート制限・ログ収集は小規模でも価値があります。AWSを使うなら最初からAPI Gatewayを挟む構成にするか、FastAPIのミドルウェアで同等の機能を実装する方法があります。マイクロサービスに分割し始めたタイミングで本格的なAPIゲートウェイの導入を検討してください。

Q: APIバージョニングはどのタイミングで必要ですか？

A: 外部クライアント（パートナー企業、モバイルアプリ）が使うAPIには最初からバージョニングを設計しておくことを推奨します。内部サービス間のAPIは、デプロイを統一して一斉更新できるなら不要な場合もあります。

Q: REST と GraphQL はどちらを選ぶべきですか？

A: フロントエンドから大量の異なるデータ型を柔軟に取得するニーズがある場合はGraphQL、シンプルなCRUDや公開APIならRESTが実装コストを抑えられます。最初はRESTで始め、フロントエンドのデータ取得が複雑になってきたらGraphQLを検討するアプローチが一般的です。

Q: gRPC をフロントエンドから直接呼べますか？

A: ブラウザからの直接呼び出しは標準のgRPCでは動作しません。grpc-webという仕様とそのプロキシを使うか、バックエンドでgRPCをHTTPに変換するトランスコーディングレイヤーを設けます。マイクロサービス間の内部通信では非常に有効です。

このページの外部仕様・背景情報は、参考文献を参照してください。[1][2][3][4][5]

参考文献

クイズ

データベース設計パターン

クラウドアーキテクチャ入門