implementing-api-patterns

API パターンのスキル

目的

ユースケースに最適なパターンとフレームワークを使用して、API を設計および実装します。API の利用者、パフォーマンス要件、型安全性のニーズに基づいて、REST、GraphQL、gRPC、tRPC から選択します。

このスキルを使用する場面

以下の場合に使用します：

• Web、モバイル、またはサービスの利用者向けにバックエンド API を構築する
• フロントエンドのコンポーネント（フォーム、テーブル、ダッシュボード）をデータベースに接続する
• ページネーション、レート制限、キャッシュ戦略を実装する
• OpenAPI ドキュメントを自動生成する
• REST、GraphQL、gRPC、tRPC のパターンから選択する
• 認証と認可を統合する
• API のパフォーマンスとスケーラビリティを最適化する

すばやく選択するためのフレームワーク

WHO CONSUMES YOUR API?
├─ PUBLIC/THIRD-PARTY DEVELOPERS → REST with OpenAPI
│  ├─ Python → FastAPI (auto-docs, 40k req/s)
│  ├─ TypeScript → Hono (edge-first, 50k req/s, 14KB)
│  ├─ Rust → Axum (140k req/s, <1ms latency)
│  └─ Go → Gin (100k+ req/s, mature ecosystem)
│
├─ FRONTEND TEAM (same org)
│  ├─ TypeScript full-stack? → tRPC (E2E type safety)
│  └─ Complex data needs? → GraphQL
│      ├─ Python → Strawberry
│      ├─ Rust → async-graphql
│      ├─ Go → gqlgen
│      └─ TypeScript → Pothos
│
├─ SERVICE-TO-SERVICE (microservices)
│  └─ High performance → gRPC
│      ├─ Rust → Tonic
│      ├─ Go → Connect-Go (browser-friendly)
│      └─ Python → grpcio
│
└─ MOBILE APPS
   ├─ Bandwidth constrained → GraphQL (request only needed fields)
   └─ Simple CRUD → REST (standard, well-understood)

REST フレームワークの選択

Python：FastAPI（推奨）

主な機能： OpenAPI ドキュメントの自動生成、Pydantic v2 による検証、async/await、40k req/s

基本的な例：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items")
async def create_item(item: Item):
    return {"id": 1, **item.dict()}

FastAPI のパターンについては references/rest-design-principles.md と examples/python-fastapi/ を参照してください。

TypeScript：Hono（エッジ優先）

主な機能： 14KB のバンドル、あらゆるランタイム（Node/Deno/Bun/edge）で動作、Zod による検証、50k req/s

基本的な例：

import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const app = new Hono()
app.post('/items', zValidator('json', z.object({
  name: z.string(), price: z.number()
})), (c) => c.json({ id: 1, ...c.req.valid('json') }))

Hono のパターンについては references/rest-design-principles.md と examples/typescript-hono/ を参照してください。

TypeScript：tRPC（フルスタックの型安全性）

主な機能： コード生成不要、エンドツーエンドの型安全性、React Query との統合、WebSocket サブスクリプション

基本的な例：

import { initTRPC } from '@trpc/server'
import { z } from 'zod'

const t = initTRPC.create()
export const appRouter = t.router({
  createItem: t.procedure
    .input(z.object({ name: z.string(), price: z.number() }))
    .mutation(({ input }) => ({ id: '1', ...input }))
})
export type AppRouter = typeof appRouter

セットアップのパターンについては references/trpc-setup-guide.md と examples/typescript-trpc/ を参照してください。

Rust：Axum（高パフォーマンス）

主な機能： Tower ミドルウェア、型安全なエクストラクター、140k req/s、コンパイル時の検証

基本的な例：

use axum::{routing::post, Json, Router};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct CreateItem { name: String, price: f64 }

#[derive(Serialize)]
struct Item { id: u64, name: String, price: f64 }

async fn create_item(Json(payload): Json<CreateItem>) -> Json<Item> {
    Json(Item { id: 1, name: payload.name, price: payload.price })
}

Axum のパターンについては references/rest-design-principles.md と examples/rust-axum/ を参照してください。

Go：Gin（成熟したエコシステム）

主な機能： 最大規模の Go エコシステム、100k+ req/s、構造体タグによる検証

基本的な例：

type Item struct {
    Name  string  `json:"name" binding:"required"`
    Price float64 `json:"price" binding:"required,gt=0"`
}

r := gin.Default()
r.POST("/items", func(c *gin.Context) {
    var item Item
    if c.ShouldBindJSON(&item); err != nil {
        c.JSON(400, gin.H{"error": err.Error()}); return
    }
    c.JSON(201, item)
})

Gin のパターンについては references/rest-design-principles.md と examples/go-gin/ を参照してください。

パフォーマンスのベンチマーク

言語	フレームワーク	Req/s	レイテンシ	コールドスタート	メモリ	最適な用途
Rust	Actix-web	~150k	<1ms	N/A	2-5MB	最大スループット
Rust	Axum	~140k	<1ms	N/A	2-5MB	使いやすさとパフォーマンス
Go	Gin	~100k+	1-2ms	N/A	5-10MB	成熟したエコシステム
TypeScript	Hono	~50k	<5ms	<5ms	128MB	エッジへのデプロイ
Python	FastAPI	~40k	5-10ms	1-2s	30-50MB	開発者体験
TypeScript	Express	~15k	10-20ms	1-3s	50-100MB	レガシーシステム

注：

• ベンチマークはシングルコア、JSON レスポンスを前提としています
• 実際のパフォーマンスはワークロードの複雑さによって異なります
• コールドスタートが適用されるのは、サーバーレス／エッジへのデプロイのみです

ページネーション戦略

カーソルベース（推奨）

利点： リアルタイムの変更に対応し、レコードのスキップや重複がなく、数十億件までスケールします

FastAPI の例：

@app.get("/items")
async def list_items(cursor: Optional[str] = None, limit: int = 20):
    query = db.query(Item).filter(Item.id > cursor) if cursor else db.query(Item)
    items = query.limit(limit).all()
    return {
        "items": items,
        "next_cursor": items[-1].id if items else None,
        "has_more": len(items) == limit
    }

オフセットベース（単純なケースのみ）

直接ページにアクセスする必要がある静的データセット（<10k 件）に限って使用してください。

パターン全般とフロントエンドとの統合については references/pagination-patterns.md を参照してください。

OpenAPI ドキュメント

フレームワーク	OpenAPI のサポート	ドキュメント UI	設定
FastAPI	自動	Swagger UI + ReDoc	組み込み
Hono	ミドルウェアプラグイン	Swagger UI	@hono/swagger-ui
Axum	utoipa crate	Swagger UI	手動アノテーション
Gin	swaggo/swag	Swagger UI	コメントアノテーション

FastAPI の例（設定不要）：

app = FastAPI(title="My API", version="1.0.0")

@app.post("/items", tags=["items"])
async def create_item(item: Item) -> Item:
    """Create item with name and price"""
    return item
# Docs at /docs, /redoc, /openapi.json

フレームワークごとのセットアップについては references/openapi-documentation.md を参照してください。 仕様をプログラムから抽出するには scripts/generate_openapi.py を使用します。

フロントエンド統合パターン

フォーム → REST POST/PUT

バックエンド：

class UserCreate(BaseModel):
    email: EmailStr; name: str; age: int

@app.post("/api/users", status_code=201)
async def create_user(user: UserCreate):
    return {"id": 1, **user.dict()}

フロントエンド：

const res = await fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(data)
})
if (!res.ok) throw new Error((await res.json()).detail)

テーブル → ページネーション付き GET

上記のカーソルページネーションの例と references/pagination-patterns.md を参照してください。

AI チャット → SSE ストリーミング

バックエンド:

from sse_starlette.sse import EventSourceResponse

@app.post("/api/chat")
async def chat(message: str):
    async def gen():
        for chunk in llm_stream(message):
            yield {"event": "message", "data": chunk}
    return EventSourceResponse(gen())

フロントエンド:

const es = new EventSource('/api/chat')
es.addEventListener('message', (e) => appendToChat(e.data))

各フロントエンドスキルとの完全な統合例については、examples/ を参照してください。

レート制限

FastAPI の例（トークンバケット）:

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter

@app.get("/items")
@limiter.limit("100/minute")
async def list_items():
    return {"items": []}

スライディングウィンドウ、分散パターン、Redis の実装については、references/rate-limiting-strategies.md を参照してください。

GraphQL ライブラリ

フロントエンドで柔軟なデータフェッチが必要な場合や、モバイルアプリで帯域幅に制約がある場合に使用します。

言語別:

• Python: Strawberry 0.287（型ヒントベース、非同期）
• Rust: async-graphql（高いパフォーマンス、tokio）
• Go: gqlgen（スキーマからコードを生成）
• TypeScript: Pothos（型安全なビルダー、コード生成不要）

スキーマパターンと N+1 の防止については、references/graphql-schema-design.md を参照してください。 Python の完全な例については、examples/graphql-strawberry/ を参照してください。

マイクロサービス向け gRPC

強い型付けと高いパフォーマンスを備えたサービス間通信に使用します。

言語別:

• Rust: Tonic（非同期、型安全、コード生成）
• Go: Connect-Go（gRPC 互換かつブラウザーに対応）
• Python: grpcio（公式実装）
• TypeScript: @connectrpc/connect（ブラウザー + Node.js）

Protocol Buffers のガイドについては、references/grpc-protobuf-guide.md を参照してください。 Rust の完全な例については、examples/grpc-tonic/ を参照してください。

その他のリソース

リファレンス

• references/rest-design-principles.md - REST リソースのモデリング、HTTP メソッド、ステータスコード
• references/graphql-schema-design.md - スキーマパターン、リゾルバーの最適化、N+1 の防止
• references/grpc-protobuf-guide.md - Proto3 の構文、サービス定義、ストリーミング
• references/trpc-setup-guide.md - ルーターパターン、ミドルウェア、Zod によるバリデーション
• references/pagination-patterns.md - 数学的な解説付きのカーソル方式とオフセット方式の比較
• references/rate-limiting-strategies.md - トークンバケット、スライディングウィンドウ、Redis
• references/caching-patterns.md - HTTP キャッシュ、アプリケーションのキャッシュ戦略
• references/versioning-strategies.md - URI、ヘッダー、メディアタイプによるバージョニング
• references/openapi-documentation.md - フレームワーク別の Swagger/OpenAPI のベストプラクティス

スクリプト（トークンを消費しない実行）

• scripts/generate_openapi.py - コードから OpenAPI 仕様を生成
• scripts/validate_api_spec.py - OpenAPI 3.1 への準拠を検証
• scripts/benchmark_endpoints.py - API エンドポイントの負荷テスト

例

• examples/python-fastapi/ - FastAPI による完全な REST API
• examples/typescript-hono/ - エッジファーストの Hono API
• examples/typescript-trpc/ - tRPC によるエンドツーエンドの型安全な API
• examples/rust-axum/ - Axum REST API
• examples/go-gin/ - Gin REST API
• examples/graphql-strawberry/ - Python GraphQL
• examples/grpc-tonic/ - Rust gRPC

クイックリファレンス

REST を選ぶ場合: パブリック API、標準的な CRUD、キャッシュが必要、OpenAPI ドキュメントが必須 GraphQL を選ぶ場合: フロントエンドで柔軟なクエリが必要、モバイルの帯域幅に制約がある、複雑なネストデータを扱う gRPC を選ぶ場合: サービス間通信、高いパフォーマンス、双方向ストリーミング tRPC を選ぶ場合: TypeScript のフルスタック、同じチームがフロントエンドとバックエンドを担当、エンドツーエンドの型安全性

ページネーション: 本番環境の規模では常にカーソル方式を使用し、オフセット方式は単純なケースに限ってください ドキュメント: OpenAPI を自動生成するフレームワーク（FastAPI、Hono）を優先してください パフォーマンス: 最大スループットには Rust（Axum）、成熟度には Go（Gin）、開発者体験には Python（FastAPI）