api-design-principles

API 設計原則

直感的でスケーラブル、かつ保守しやすい API を構築し、開発者を満足させ、長く使われ続けるために、REST と GraphQL の 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 設計原則

スキーマファースト開発

• 型がドメインモデルを定義する
• データの読み取りにはクエリ
• データの変更にはミューテーション
• リアルタイム更新にはサブスクリプション

クエリ構造：

• クライアントは必要なものだけを正確に要求する
• 単一のエンドポイント、複数の操作
• 強い型付けのスキーマ
• イントロスペクションを標準搭載

3. API バージョニング戦略

URL バージョニング：

/api/v1/users
/api/v2/users

ヘッダーバージョニング：

Accept: application/vnd.api+json; version=1

クエリパラメータバージョニング：

/api/users?version=1

詳細なパターンと実例

詳細なパターンのドキュメントは references/details.md にあります。上記のナビゲーション階層では不十分な場合に、そのファイルを読んでください。

ベストプラクティス

REST API

1. 一貫した命名：コレクションには複数形の名詞を使用する（/user ではなく /users）
2. ステートレス：各リクエストに必要な情報をすべて含める
3. HTTP ステータスコードを正しく使う：2xx は成功、4xx はクライアントエラー、5xx はサーバーエラー
4. API をバージョニングする：初日から破壊的変更に備えて計画する
5. ページネーション：大きなコレクションには常にページネーションを適用する
6. レート制限：レート制限で API を保護する
7. ドキュメント：インタラクティブなドキュメントには OpenAPI/Swagger を使用する

GraphQL API

1. スキーマファースト：リゾルバーを書く前にスキーマを設計する
2. N+1 を避ける：効率的なデータ取得には DataLoader を使用する
3. 入力バリデーション：スキーマとリゾルバーの両方のレベルで検証する
4. エラーハンドリング：ミューテーションのペイロードで構造化されたエラーを返す
5. ページネーション：カーソルベースのページネーションを使用する（Relay 仕様）
6. 非推奨化：段階的な移行には @deprecated ディレクティブを使用する
7. モニタリング：クエリの複雑さと実行時間を追跡する

よくある落とし穴

• 過剰フェッチ／過少フェッチ（REST）：GraphQL では解消されるが、DataLoader が必要
• 破壊的変更：API をバージョニングするか、非推奨化戦略を用いる
• 一貫性のないエラー形式：エラーレスポンスを標準化する
• レート制限の欠如：制限のない API は悪用に対して脆弱
• 貧弱なドキュメント：ドキュメントのない API は開発者をいら立たせる
• HTTP セマンティクスの無視：冪等な操作に POST を使うと期待を裏切る
• 密結合：API の構造はデータベーススキーマをそのまま反映すべきではない