はじめに
この章では、本資料の目的と構成、想定読者について簡潔に説明します。REST APIのURL設計は、可読性・拡張性・保守性に直結します。適切な命名や一貫したルールを決めることで、開発や運用がずっと楽になります。
目的
本資料は、リソース指向の考え方に基づくURL設計のベストプラクティスをまとめたものです。具体的な例や注意点を交えて、分かりやすく実践的に伝えます。
想定読者
API設計や実装に関わるエンジニア、プロダクト担当者、フロントエンド開発者を想定します。専門用語は最小限に抑え、初めて設計ルールを決める方にも役立つ内容にしています。
本資料で扱う主な項目
- URL命名規則とパターン
- 階層構造とネストリソースの表現
- フィルタ・ソート・ページネーション設計
- バージョニングの扱い方
- プラットフォーム別の実装例（WordPress含む）
使い方
各章は独立して参照できますが、最初から順に読むと設計の考え方がつかみやすくなります。実務に当てはめる際は、まずサービス全体で採用する基本ルールを決め、その後で例外や詳細仕様を詰めてください。
REST APIのURL設計とは
概要
REST APIのURL設計は、各リソース（ユーザー・記事・注文など）に一意の住所を割り当てる作業です。URLだけで何の情報にアクセスするのか直感的に分かることが大切です。操作はHTTPメソッド（GET, POST, PUT, DELETEなど）で区別します。
何を表すか
URLは“名詞”で表現します。リソース名は複数形を使うのが一般的です（例: /users, /articles）。個別の要素はIDで指定します（例: /users/12345）。
構成と具体例
基本構成は「スキーム + ドメイン + パス」。APIの共通プレフィックスを置くと管理しやすくなります。
例: https://example.com/api/users/12345
ここで「api」はプレフィックス、「users」がリソース、「12345」がIDです。
設計のポイント
- 名詞を使う：動詞をURLに入れない（/getUserではなく/users/12345）。
- 一貫性を保つ：小文字・ハイフン・複数形を揃える。
- 意味を優先：URLだけで何を表すか分かるようにする。
HTTPメソッドとの役割分担
- GET: 取得、POST: 作成、PUT/PATCH: 更新、DELETE: 削除。URLは対象を指し、メソッドで操作を決めます。
補足（フィルタ等）
検索や絞り込みはクエリパラメータを使います（例: /articles?author=alice&page=2）。
この章では、直感的で管理しやすいURL作りの基本を押さえておくことが重要です。
REST API URL設計のベストプラクティス
概要
読みやすく、拡張しやすいURLを決めると運用が楽になります。ここでは具体的な指針と例を示します。
主要なルールと例
- リソース名は名詞で、動詞を含めない。
例: /orders（正） vs /createOrder（誤） - 複数形を使う。
例: /users, /products - 階層構造はスラッシュで表現する。
例: /users/123/orders/456 - 小文字・ハイフン区切りで可読性を高める。
例: /user-profiles（推奨） vs /user_profiles - ファイル拡張子は付けない。
例: /items.json は不要 - バージョン番号をURLに含める（安定した互換性のため）。
例: /api/v1/users - 短く意味のある名前を選ぶ。
長く曖昧な名前は避け、意図が伝わる単語を使います。 - IDはパスに、フィルタやソートはクエリに。
例: /products/123、/products?sort=price&category=books
運用上の注意
命名規則をチームで決めてドキュメント化してください。統一ルールがあると拡張や保守が楽になります。
階層構造・ネストリソースの表現
概要
リソース同士の関係はURLの階層で表現できます。親子や所属を明示できるため、利用者に分かりやすい設計になります。
基本例
- ユーザーの投稿一覧: /users/123/posts
- 特定の投稿: /users/123/posts/456
新規投稿はPOSTメソッドで /users/123/posts に送ります。
リクエスト例（簡潔）
- GET /users/123/posts → そのユーザーの投稿一覧を取得
- GET /users/123/posts/456 → 投稿456の詳細を取得
- POST /users/123/posts → ボディに投稿データを入れて新規作成
ネストの判断基準
ネストは「親のコンテキストが必要な場合」に使います。たとえば投稿は常にユーザーに紐づくならネストが有効です。一方、複数の親で共有されるリソースや単独で参照される場合はトップレベルに置く方が扱いやすくなります。
過度なネストを避ける
3階層以上の深いネストはURLが長くなり可読性が落ちます。代替としてクエリや独立したエンドポイントを使います。例: /posts?user=123 や /posts/456（ownerフィールドで関連を保持）
注意点
- 一意の識別子(ID)はURLに含める。
- ネストは意味を持たせるために使い、見せかけの階層は避ける。
- 認可やパーミッションは親子関係を考慮して実装する。
フィルタ・ソート・ページネーションの設計
概要
一覧取得APIでは検索・絞り込み・並び替え・ページ分けをクエリパラメータで実現します。使いやすさと一貫性を重視して設計します。
フィルタ
基本はキー=値で渡します。例: /posts?author=123&status=active。複数値はカンマ区切りか同名パラメータを繰り返します（tags=foo,bar または tags=foo&tags=bar）。演算子は必要に応じて gt, lt, gte, lte を使うか、price_min=100&price_max=500 のように明示します。複雑な条件は JSON を filter= に入れる方式も採れますが、可読性とキャッシュ性を考慮してから導入してください。
ソート
単一: /posts?sort=created_at&order=desc。複数は符号付きで sort=-created_at,name のようにすると短く扱えます。必ずデフォルトソートを決め、安定した順序を返すようにします。
ページネーション
代表的な方式は3つです。
– limit/offset: /users?limit=10&offset=20（単純で扱いやすい）。
– page/size: /users?page=3&size=10（人間向け）。
– cursor: /posts?limit=10&cursor=xyz（大規模データに有利、性能が安定）。
offset は大きな値で遅くなるため上限を設け、cursor 方式を推奨する場面を検討してください。レスポンスには現在のページ情報を含めます（例: total_count, limit, offset または next_cursor, prev_cursor）。
命名と安全策
パラメータ名はプロジェクト全体で統一します（例: limit/offset または page/size）。limit の最大値を設定し無制限の取得を防ぎます。
バージョニングの扱い
目的と基本方針
APIは長期運用で仕様が変わります。バージョンを明示すると互換性を守りつつ段階的に移行できます。例: /v1/users、/api/v2/articles。
バージョンの置き場所（URL とヘッダー）
- URL（例: /v1/users）: 発見性が高く、クライアントに分かりやすい。公開APIで推奨します。
- ヘッダー（例: X-API-Version: 2 や Accept: application/vnd.example.v2+json）: URLを変えたくない場合に有効。クライアント実装がやや複雑になります。
バージョン番号の付け方
メジャー番号は互換性を壊す変更、マイナーは後方互換な追加、パッチはバグ修正に使います。URLには通常メジャーバージョンのみを置きます。
非互換変更と移行戦略
破壊的変更は新しいバージョンで提供します。同時運用期間を設け、移行ガイドやサンプルを用意します。レスポンスに警告ヘッダー（例: Deprecation）を入れると役立ちます。
実運用での注意点
バージョンごとにドキュメント・テストを用意し、サポート期間を明確にします。小さな変更は互換性を保つ方法を優先し、頻繁なメジャーアップは避けます。
実装例（WordPressの場合）
概要
WordPressではregister_rest_route()でカスタムエンドポイントを追加します。名前空間（例：myplugin/v1）でバージョン管理し、ルート（例：/latest-posts/）でエンドポイントを指定します。許可するHTTPメソッド、コールバック、パーミッション設定を行います。
基本的な登録例
add_action('rest_api_init', function() {
register_rest_route('myplugin/v1', '/latest-posts/', [
'methods' => 'GET',
'callback' => 'myplugin_get_latest_posts',
'permission_callback' => '__return_true',
'args' => [
'count' => [ 'validate_callback' => 'is_numeric', 'sanitize_callback' => 'absint' ]
]
]);
});
コールバック例
function myplugin_get_latest_posts(WP_REST_Request $request){
$count = $request->get_param('count') ?: 5;
$posts = get_posts(['numberposts'=>absint($count)]);
return rest_ensure_response($posts);
}
パーミッションとバリデーション
permission_callbackでアクセス制御を行います。current_user_can()やnonce検証を使います。argsでvalidate_callbackとsanitize_callbackを指定し、悪意ある入力を防ぎます。
レスポンス設計とエラー処理
rest_ensure_response()で標準レスポンスを返します。エラー時はWP_Errorを返し、適切なHTTPステータスを設定します。
実運用のポイント
- キャッシュやページネーションを検討する
- 出力は必要最小限のフィールドにする
- 認証・権限チェックを必ず行う
これらを踏まえて実装すれば、堅牢で扱いやすいエンドポイントを作成できます。
API設計時の注意点・よくある落とし穴
概要
API設計では小さなズレが使い勝手や保守性に大きく影響します。よくある落とし穴を挙げ、具体例と対処法を示します。
1. 動詞や操作名をURLに含めない
NG: /create-user, /getPosts
OK: /users (POSTで作成、GETで取得)
説明: HTTPメソッドで操作を分けることで一貫性を保てます。
2. リソース名の不統一
NG: /user, /users, /Users
OK: /users（複数形を統一）
説明: 同じ意味で別名があると混乱します。
3. 過度なネストを避ける
NG: /users/123/orders/456/items/789/reviews
代替: /orders/456/items/789/reviews または /users/123/orders といった参照リンクを併用
説明: 深すぎるネストはURL長と複雑さを招きます。
4. ファイル拡張子や大文字を使わない
NG: /users.json, /Users/123
OK: /users, /users/123
説明: 拡張子は表現層に依存し、ケース感度は環境差を生みます。
5. クエリパラメータ命名の不統一
例: ?page=2 vs ?Page=2 vs ?page_size=10
対処: 命名規則（snake_caseかcamelCase、統一ルール）を決める
6. バージョン管理を怠らない
説明: v1をURLに含めるか、ヘッダーで管理します。変更時の互換性を確保してください。
実践的チェックリスト
- 動詞をURLに含めない
- リソース名を統一する
- ネストは浅めに設計する
- 拡張子・大文字を避ける
- クエリ命名ルールを決める
- バージョン戦略を用意する
これらを守ると、保守しやすいAPIになります。
まとめとツール活用
REST APIのURL設計は「リソースを分かりやすく表現すること」と「一貫性のあるルールを守ること」が肝心です。URLの命名、階層構造、フィルタやページング、バージョン管理を設計段階で決めると、後の運用と連携が楽になります。
実践ワークフロー（おすすめ）
- 仕様書を作る：OpenAPI（旧Swagger）やApidogでAPIの仕様を書きます。UIで編集でき、他のメンバーと共有しやすいです。
- 自動生成：仕様からドキュメントやクライアント／サーバーの雛形を生成します。作業量を減らせます。
- モックと検証：PostmanやOpenAPIのモック機能で動作を確認します。本番前の差し替えが簡単です。
- テストとCI：契約テストや自動テストをCIに組み込み、破壊的変更を早期に検出します。
- リントと品質管理：Spectralなどで仕様のチェックを自動化します。
ツール別の使いどころ（簡潔）
- OpenAPI／Swagger：仕様の記述とドキュメント生成に最適。エコシステムが豊富です。
- Apidog：GUIで編集や共有がしやすく、小規模チームに向きます。
- Postman：モックや手動テスト、コレクション共有に便利です。
- Spectral：スキーマのルールチェックに使えます。
運用のポイント（短く）
- 仕様はリポジトリで管理し、変更はレビューする。自動生成物はビルド時に作る。
- バージョンは意図的に上げ、後方互換性を意識して変更する。
この章を基に、設計→仕様化→自動化の順で進めると、実務で安定したAPI運用が実現できます。
