API 設計原則
REST と GraphQL の API 設計原則を習得し、直感的でスケーラブル、かつ保守性の高い API を構築して、開発者を魅了し、時代に耐えるものにしましょう。
このスキルを使用するタイミング
- 新しい REST または GraphQL API を設計する場合
- 既存の API をより使いやすくリファクタリングする場合
- チームの API 設計標準を確立する場合
- 実装前に API 仕様をレビューする場合
- API パラダイム間の移行(REST から GraphQL など)を行う場合
- 開発者にとって使いやすい API ドキュメントを作成する場合
- 特定のユースケース(モバイル、サードパーティ連携など)向けに API を最適化する場合
中核概念
1. RESTful 設計原則
リソース指向アーキテクチャ
- リソースは名詞(users、orders、products)であり動詞ではない
- アクションには HTTP メソッドを使用(GET、POST、PUT、PATCH、DELETE)
- URL はリソース階層を表現する
- 一貫性のある命名規則を使用する
HTTP メソッドのセマンティクス:
GET: リソースの取得(べき等、安全)POST: 新しいリソースの作成PUT: リソース全体の置き換え(べき等)PATCH: リソースの部分更新DELETE: リソースの削除(べき等)
2. GraphQL 設計原則
スキーマファースト開発
- 型(Types)がドメインモデルを定義する
- クエリ(Queries)はデータ読み取り用
- ミューテーション(Mutations)はデータ変更用
- サブスクリプション(Subscriptions)はリアルタイム更新用
クエリ構造:
- クライアントは必要なものを正確にリクエストする
- 単一のエンドポイント、複数の操作
- 厳密に型付けされたスキーマ
- イントロスペクションが組み込まれている
3. API バージョニング戦略
URL バージョニング:
/api/v1/users
/api/v2/users
ヘッダーバージョニング:
Accept: application/vnd.api+json; version=1
クエリパラメータバージョニング:
/api/users?version=1
REST API 設計パターン
パターン 1: リソースコレクション設計
# Good: リソース指向のエンドポイント
GET /api/users # ユーザー一覧(ページネーション付き)
POST /api/users # ユーザーを作成
GET /api/users/{id} # 特定のユーザーを取得
PUT /api/users/{id} # ユーザーを置き換え
PATCH /api/users/{id} # ユーザーフィールドを更新
DELETE /api/users/{id} # ユーザーを削除
# ネストされたリソース
GET /api/users/{id}/orders # ユーザーの注文を取得
POST /api/users/{id}/orders # ユーザーの注文を作成
# Bad: アクション指向のエンドポイント(避ける)
POST /api/createUser
POST /api/getUserById
POST /api/deleteUser
パターン 2: ページネーションとフィルタリング
from typing import List, Optional
from pydantic import BaseModel, Field
class PaginationParams(BaseModel):
page: int = Field(1, ge=1, description="ページ番号")
page_size: int = Field(20, ge=1, le=100, description="1ページあたりのアイテム数")
class FilterParams(BaseModel):
status: Optional[str] = None
created_after: Optional[str] = None
search: Optional[str] = None
class PaginatedResponse(BaseModel):
items: List[dict]
total: int
page: int
page_size: int
pages: int
@property
def has_next(self) -> bool:
return self.page < self.pages
@property
def has_prev(self) -> bool:
return self.page > 1
# FastAPI エンドポイントの例
from fastapi import FastAPI, Query, Depends
app = FastAPI()
@app.get("/api/users", response_model=PaginatedResponse)
async def list_users(
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=100),
status: Optional[str] = Query(None),
search: Optional[str] = Query(None)
):
# フィルターを適用
query = build_query(status=status, search=search)
# 総数をカウント
total = await count_users(query)
# ページを取得
offset = (page - 1) * page_size
users = await fetch_users(query, limit=page_size, offset=offset)
return PaginatedResponse(
items=users,
total=total,
page=page,
page_size=page_size,
pages=(total + page_size - 1) // page_size
)
パターン 3: エラーハンドリングとステータスコード
from fastapi import HTTPException, status
from pydantic import BaseModel
class ErrorResponse(BaseModel):
error: str
message: str
details: Optional[dict] = None
timestamp: str
path: str
class ValidationErrorDetail(BaseModel):
field: str
message: str
value: Any
# 一貫性のあるエラーレスポンス
STATUS_CODES = {
"success": 200,
"created": 201,
"no_content": 204,
"bad_request": 400,
"unauthorized": 401,
"forbidden": 403,
"not_found": 404,
"conflict": 409,
"unprocessable": 422,
"internal_error": 500
}
def raise_not_found(resource: str, id: str):
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail={
"error": "NotFound",
"message": f"{resource} が見つかりません",
"details": {"id": id}
}
)
def raise_validation_error(errors: List[ValidationErrorDetail]):
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail={
"error": "ValidationError",
"message": "リクエストのバリデーションに失敗しました",
"details": {"errors": [e.dict() for e in errors]}
}
)
# 使用例
@app.get("/api/users/{user_id}")
async def get_user(user_id: str):
user = await fetch_user(user_id)
if not user:
raise_not_found("User", user_id)
return user
パターン 4: HATEOAS(アプリケーション状態のエンジンとしてのハイパーメディア)
class UserResponse(BaseModel):
id: str
name: str
email: str
_links: dict
@classmethod
def from_user(cls, user: User, base_url: str):
return cls(
id=user.id,
name=user.name,
email=user.email,
_links={
"self": {"href": f"{base_url}/api/users/{user.id}"},
"orders": {"href": f"{base_url}/api/users/{user.id}/orders"},
"update": {
"href": f"{base_url}/api/users/{user.id}",
"method": "PATCH"
},
"delete": {
"href": f"{base_url}/api/users/{user.id}",
"method": "DELETE"
}
}
)
GraphQL 設計パターン
パターン 1: スキーマ設計
# schema.graphql
# 明確な型定義
type User {
id: ID!
email: String!
name: String!
createdAt: DateTime!
# リレーションシップ
orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!
profile: UserProfile
}
type Order {
id: ID!
status: OrderStatus!
total: Money!
items: [OrderItem!]!
createdAt: DateTime!
# 逆参照
user: User!
}
# ページネーションパターン(Relay スタイル)
type OrderConnection {
edges: [OrderEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type OrderEdge {
node: Order!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
# 型安全性のための Enum
enum OrderStatus {
PENDING
CONFIRMED
SHIPPED
DELIVERED
CANCELLED
}
# カスタムスカラー
scalar DateTime
scalar Money
# クエリルート
type Query {
user(id: ID!): User
users(first: Int = 20, after: String, search: String): UserConnection!
order(id: ID!): Order
}
# ミューテーションルート
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
updateUser(input: UpdateUserInput!): UpdateUserPayload!
deleteUser(id: ID!): DeleteUserPayload!
createOrder(input: CreateOrderInput!): CreateOrderPayload!
}
# ミューテーション用の入力型
input CreateUserInput {
email: String!
name: String!
password: String!
}
# ミューテーション用のペイロード型
type CreateUserPayload {
user: User
errors: [Error!]
}
type Error {
field: String
message: String!
}
パターン 2: リゾルバ設計
from typing import Optional, List
from ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass
query = QueryType()
mutation = MutationType()
user_type = ObjectType("User")
@query.field("user")
async def resolve_user(obj, info, id: str) -> Optional[dict]:
"""ID で単一ユーザーを解決します。"""
return await fetch_user_by_id(id)
@query.field("users")
async def resolve_users(
obj,
info,
first: int = 20,
after: Optional[str] = None,
search: Optional[str] = None
) -> dict:
"""ページネーションされたユーザー一覧を解決します。"""
# カーソルをデコード
offset = decode_cursor(after) if after else 0
# ユーザーを取得
users = await fetch_users(
limit=first + 1, # hasNextPage を確認するために1つ多く取得
offset=offset,
search=search
)
# ページネーション
has_next = len(users) > first
if has_next:
users = users[:first]
edges = [
{
"node": user,
"cursor": encode_cursor(offset + i)
}
for i, user in enumerate(users)
]
return {
"edges": edges,
"pageInfo": {
"hasNextPage": has_next,
"hasPreviousPage": offset > 0,
"startCursor": edges[0]["cursor"] if edges else None,
"endCursor": edges[-1]["cursor"] if edges else None
},
"totalCount": await count_users(search=search)
}
@user_type.field("orders")
async def resolve_user_orders(user: dict, info, first: int = 20) -> dict:
"""ユーザーの注文を解決します(DataLoader による N+1 防止)。"""
# DataLoader を使用してリクエストをバッチ処理
loader = info.context["loaders"]["orders_by_user"]
orders = await loader.load(user["id"])
return paginate_orders(orders, first)
@mutation.field("createUser")
async def resolve_create_user(obj, info, input: dict) -> dict:
"""新規ユーザーを作成します。"""
try:
# 入力を検証
validate_user_input(input)
# ユーザーを作成
user = await create_user(
email=input["email"],
name=input["name"],
password=hash_password(input["password"])
)
return {
"user": user,
"errors": []
}
except ValidationError as e:
return {
"user": None,
"errors": [{"field": e.field, "message": e.message}]
}
パターン 3: DataLoader(N+1 問題の防止)
from aiodataloader import DataLoader
from typing import List, Optional
class UserLoader(DataLoader):
"""ID でユーザーをバッチロードします。"""
async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
"""複数のユーザーを単一のクエリでロードします。"""
users = await fetch_users_by_ids(user_ids)
# 結果を入力順にマッピング
user_map = {user["id"]: user for user in users}
return [user_map.get(user_id) for user_id in user_ids]
class OrdersByUserLoader(DataLoader):
"""ユーザー ID で注文をバッチロードします。"""
async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
"""複数ユーザーの注文を単一のクエリでロードします。"""
orders = await fetch_orders_by_user_ids(user_ids)
# 注文を user_id でグループ化
orders_by_user = {}
for order in orders:
user_id = order["user_id"]
if user_id not in orders_by_user:
orders_by_user[user_id] = []
orders_by_user[user_id].append(order)
# 入力順に返却
return [orders_by_user.get(user_id, []) for user_id in user_ids]
# コンテキストのセットアップ
def create_context():
return {
"loaders": {
"user": UserLoader(),
"orders_by_user": OrdersByUserLoader()
}
}
ベストプラクティス
REST API
- 一貫性のある命名: コレクションには複数形の名詞を使用する(
/users、/userではない) - ステートレス: 各リクエストに必要な情報をすべて含める
- HTTP ステータスコードを正しく使用する: 2xx 成功、4xx クライアントエラー、5xx サーバーエラー
- API をバージョニングする: 初日から破壊的変更に備える
- ページネーション: 大規模なコレクションは常にページネーションする
- レート制限: API をレート制限で保護する
- ドキュメント: 対話型ドキュメントには OpenAPI/Swagger を使用する
GraphQL API
- スキーマファースト: リゾルバを作成する前にスキーマを設計する
- N+1 を避ける: 効率的なデータ取得に DataLoader を使用する
- 入力検証: スキーマとリゾルバの両方のレベルで検証する
- エラーハンドリング: ミューテーションペイロードで構造化されたエラーを返す
- ページネーション: カーソルベースのページネーションを使用する(Relay 仕様)
- 非推奨化: 段階的な移行には
@deprecatedディレクティブを使用する - モニタリング: クエリの複雑さと実行時間を追跡する
よくある落とし穴
- 過剰取得/過小取得(REST): GraphQL では解決されるが、DataLoader が必要
- 破壊的変更: API をバージョニングするか、非推奨化戦略を使用する
- 一貫性のないエラーフォーマット: エラーレスポンスを標準化する
- レート制限の欠如: 制限のない API は悪用されやすい
- 不十分なドキュメント: ドキュメント化されていない API は開発者をイライラさせる
- HTTP セマンティクスの無視: べき等な操作に POST を使うと期待を裏切る
- 密結合: API 構造がデータベーススキーマを反映すべきではない
リソース
- references/rest-best-practices.md: 包括的な REST API 設計ガイド
- references/graphql-schema-design.md: GraphQL スキーマパターンとアンチパターン
- references/api-versioning-strategies.md: バージョニングアプローチと移行パス
- assets/rest-api-template.py: FastAPI REST API テンプレート
- assets/graphql-schema-template.graphql: 完全な GraphQL スキーマ例
- assets/api-design-checklist.md: 実装前レビューチェックリスト
- scripts/openapi-generator.py: コードから OpenAPI 仕様を生成