はじめに
概要
本ドキュメントはREST URL設計に関する複数の記事を整理したガイドです。主にリソース中心の設計、HTTPメソッドの使い分け、バージョニング、命名規則、URIの階層構造、エラーハンドリング、セキュリティ対策など、API設計の基本かつ重要なポイントを分かりやすく解説します。
本書の目的
実務で使える設計方針と具体例を示し、誰でも再現できるルールを提供します。設計の判断に迷ったときに参照できる実践的なリファレンスを目指しています。
想定読者
API設計者、バックエンド開発者、プロダクトマネージャー向けです。HTTPの基礎知識があれば読み進められます。専門用語は最小限にし、具体例で補足します。
使い方
章ごとにテーマ別に整理しています。まず全体を把握し、必要な章だけ参照してください。サンプルURLやJSON例を豊富に載せるので、実装にそのまま使えます。
範囲と注意点
本書はRESTスタイルに焦点を当てます。認証や運用の詳細は触れますが、特定のフレームワーク限定の実装ガイドは扱いません。設計方針は一般的なベストプラクティスに基づきます。
表記と前提
- リソース名は複数形、英小文字、ハイフン推奨
- 動詞ではなく名詞で表現
- バージョンはパスまたはヘッダーで管理
- エラーはHTTPステータス＋JSON本文で返す
これらを前提に、次章から具体的な設計方法を丁寧に説明します。
RESTful API設計ベストプラクティス完全ガイド：実践的な方法
はじめに
REST設計はリソースを中心に考えることが基本です。URLは動詞ではなく名詞で表し、APIの直感性と拡張性を高めます。
リソース中心の設計
URLは名詞（複数形）で表現します。例えば良い例は
– GET /users
– GET /users/123
悪い例は GET /getUsers や POST /createUser です。階層構造は親子関係を示します（/users/123/orders）。
URLとバージョニング
APIの進化にはパスベースのバージョニングを推奨します。例: /api/v1/users, /api/v2/users。クエリやヘッダでのバージョン管理は分かりにくくなりやすいです。
HTTPメソッドの使い分け
- GET: 読み取り（GET /users）
- POST: 作成（POST /users）
- PUT: 全体更新（PUT /users/123）
- PATCH: 部分更新（PATCH /users/123）
- DELETE: 削除（DELETE /users/123）
冪等性（同じ操作の繰返しで結果が変わらないこと）を意識してください。
ステータスコードとエラーハンドリング
成功や失敗を適切なHTTPステータスで返します。例: 200, 201, 204, 400, 401, 403, 404, 409, 422, 500。エラーレスポンスには原因と対処法を簡潔に含めると利用者に親切です。
セキュリティとテスト
認証はBearerトークンやOAuthを使い、通信はTLSで保護します。入力の検証、レート制限、ログ記録も重要です。テストは単体・結合・契約テストを組み合わせ、安定したAPIを維持してください。
RESTful APIの設計とドキュメント作成のベストプラクティス
エンドポイント設計
リソース指向でシンプルに設計します。例：/users、/products/{id}、/orders。複数形を使い一貫性を保ちます。階層で関係を表すときはネストを深くしすぎないようにします。
HTTPメソッドの使い分け
GET（取得）、POST（作成）、PUT/PATCH（更新）、DELETE（削除）を明確に使い分けます。例：POST /productsで作成、PUT /products/{id}で全体更新、PATCHで部分更新します。適切なステータスコード（201、200、204、404など）を返します。
パラメータの扱い
パスパラメータはリソース識別、クエリパラメータはフィルタやページングに使います。例：GET /products?category=books&page=2。複雑な関係はサブリソースやリンクで表現します。
バージョニング
後方互換性を守るためにバージョンを導入します。URIバージョン（/v1/products）やヘッダーバージョンの方法があります。破壊的変更は新バージョンを作成します。
ドキュメント作成のポイント
OpenAPIなどを使って仕様を機械可読にします。各エンドポイントにリクエスト例・レスポンス例、エラー例を載せると使いやすくなります。サンプルコードやcurl例を用意すると理解が早まります。
REST API設計入門
概要
REST APIはリソース（データの対象）を扱う設計思想です。ここでは誰でも読みやすく実装しやすい基本ルールを丁寧に説明します。
命名規則
- リソース名は複数形にします。例: /users, /orders
- 名詞で表現し、動詞は避けます。例: /usersではなく/postUser
- ケバブケース（kebab-case）やスネークケース（snake_case）はプロジェクトで統一します。例: /user-profiles または /user_profiles
リソース設計とネスト
- ネストは親子関係が明確なときのみ使います。例: /users/{userId}/orders
- 深いネストは避けます。代わりにクエリで関連付けを表現します。例: /orders?userId=123
クエリパラメータ（フィルタ・ソート・ページネーション）
- フィルタ: /products?category=books&available=true
- ソート: /items?sort=price_asc
- ページネーション: page/limit方式（?page=2&limit=20）やカーソル方式を用途に応じて使います。
HTTPメソッドとステータスコード
- GET: 取得（安全、冪等）
- POST: 作成（非冪等）
- PUT/PATCH: 更新（PUTは全体、PATCHは部分）
- DELETE: 削除
- 代表的なステータス: 200, 201, 204, 400, 401, 404, 409, 500
実践のポイント
- API仕様はサンプルを含めて文書化します。
- 破壊的変更は避け、バージョン管理で対応します。
- エラー応答は一貫したフォーマット（code, message, detailsなど）にします。
RESTful Web API 設計のベスト プラクティス – Azure
1. リソース設計とURI
リソースは名詞で表現し、複数形を使います。階層は親子関係だけに限定します。例: /subscriptions/{subId}/resourceGroups/{rg}/providers/MyApp/orders
2. バージョニング
URLにバージョンを含めます（例: /v1/orders）。Azureの慣例に倣い、後方互換性を重視します。
3. 認証と認可
Azure ADのBearerトークンを使います。Authorizationヘッダに “Bearer {token}” を設定し、スコープやロールで権限を管理します。
4. HTTP動詞と振る舞い
POSTはコレクションに送りサーバーが新しいURIを割り当てます。PUTは完全な表現で置換または作成（idempotent）します。PATCHは部分更新に使います。
5. エラーハンドリングとステータスコード
標準的なHTTPステータスを返し、エラー本文にcode, message, targetを含めます。例: 404, 400, 429（レート制限）。
6. スケーラビリティと信頼性
短時間の再試行（exponential backoff）やIdempotency-Keyヘッダを使って重複処理を避けます。Application Insightsで監視します。
7. ドキュメントと互換性
OpenAPIで明確に定義し、API Managementで公開やポリシー（レート制限、変換）を適用します。
8. パフォーマンスとページング
大きな一覧はページング（continuation token）を使い、フィルタと選択（$filter, $select相当）で転送量を減らします。
実運用ではこれらを組み合わせて、直感的で安全なAPIを提供します。
エンジニアが知るべきAPI設計のベストプラクティス
命名規則とリソース設計
API成功の鍵は一貫した命名です。リソース名は名詞にし、動詞はHTTPメソッドに任せます。例: GET /users, POST /orders。リソース階層は自然な関係で表現します（例: GET /users/{id}/orders）。
ケースの一貫性
URL内はキャメルケース（userProfiles）かスネークケース（user_profiles）を選び、全てのエンドポイントで統一してください。小文字＋ハイフン（kebab-case）は可読性が高いので代替として検討できます。
HTTPメソッドと意味
GETは取得、POSTは作成、PUTは全体更新、PATCHは部分更新、DELETEは削除に使います。安全性や冪等性を意識して設計します。
バージョニング
破壊的変更が必要な場合はバージョンを付けます（例: /v1/users）。URIに入れる方法とヘッダーで管理する方法がありますが、一貫して運用してください。
ページング・フィルタ・ソート
大量データはページングで扱います。例: GET /products?limit=20&offset=40。フィルタやソートはクエリパラメータで表現します（例: ?category=books&sort=price_desc）。
エラー設計とHTTPステータス
適切なステータスを返し、エラー本文は機械処理しやすい構造にします。例: {“code”:”INVALID_INPUT”,”message”:”名前が必要です”,”details”:{…}}。
セキュリティと互換性
認証・認可は一貫して実装し、公開APIではレート制限やスロットリングを設けてください。後方互換性を保つ工夫（デフォルト値、非推奨の告知）も重要です。
例（まとめない）
- ユーザー取得: GET /users
- 注文作成: POST /orders
- 商品一覧: GET /products?category=books&limit=10
これらを一貫して運用すると、開発者に優しいAPIになります。
完全解説：REST APIでのURLとURIの違い
URIとURLの違い
URIは「リソースを一意に識別する名前」です。URLはそのリソースにアクセスするための「位置（ロケータ）」を示します。実務では多くの場合、同じ文字列が両方の意味で使われますが、本質は区別されます。
具体例
- URI（識別子）: /users/123 は「ID 123 のユーザー」を指す識別子です。
- URL（アクセス先）: https://api.example.com/users/123 はそのリソースにアクセスするための完全な場所です。
エンドポイント設計のアプローチ
- リソース操作（リソース指向）: /users、/users/{id}/orders のように名詞で表現します。状態変更はHTTPメソッドで表します（GET, POST, PUT, DELETE）。
- プロセス実行（アクション指向）: /users/{id}/activate のように動詞を使う場合、明確なビジネス操作を表すときに使いますが、過度に増やすとAPIが散らかります。
設計上のポイント
- 階層はリソースの関係を示すために使う（/users/{id}/orders）。
- フィルタや検索はクエリ文字列に（/orders?status=shipped）。
- パスに動詞を置かない（/getUser は避ける）。
注意点
URIは抽象的な識別、URLは実際のアクセス先という考えを持つと設計がぶれません。実用面ではURLを意識して、安定したURI設計を行ってください。
