はじめに
本記事の目的
本記事はRESTful APIのURL設計に関する実用的なベストプラクティスを分かりやすく解説します。設計の基本から命名、パラメータの扱い、バージョン管理、保守性や検索性を意識した作り方まで網羅します。
誰のための記事か
バックエンド／フロントエンドの開発者、API設計に関わる方、これからAPIを作るエンジニアなど、実務で使える知識を求める人向けです。専門用語は最小限に留め、具体例で補足します。
読み方の案内
各章は独立して読めますが、まずは全体の方針を本章で把握してください。実例と注意点を交え、すぐに使える設計ポイントを順を追って説明します。今後の章で具体的な設計ルールと落とし穴を丁寧に示します。
RESTful APIにおけるURL設計の基本原則
概要
REST APIでは各リソースに一意のURLを割り当てます。URLはリソースを指す名詞で表現し、操作はHTTPメソッド（GET/POST/PUT/DELETE）で表現します。たとえばユーザー情報は /users/12345 のように表します。
基本原則
- 名詞を使う：URLはリソース名（複数形が一般的）で表します。例：/users, /orders
- 動詞は使わない：作成や検索などの操作はHTTPメソッドで行います。したがって /users/12345 をGETで取得、PUTで更新します。
- 一意性を保つ：各リソースに固有のIDを割り当てます。例：/products/987
階層とリソース関係
親子関係は階層で表現します。例：/products/987/reviews は製品987のレビュー集合を示します。コレクションと要素を区別すると理解しやすくなります。
具体例
- GET /users — ユーザー一覧
- POST /users — ユーザー作成
- GET /users/12345 — ユーザー取得
- DELETE /users/12345 — ユーザー削除
注意点
- 小文字とハイフンを使う：/order-items のように可読性を高めます。
- バージョンはパスかヘッダで管理：/v1/orders など。用途に合わせて一貫して使ってください。
実践チェックリスト
- URLは名詞か？
- HTTPメソッドで操作を表現しているか？
- IDや階層で一意に表現できるか？
次章では命名規則と具体的なパス設計を詳しく見ていきます。
命名規則とパス設計のベストプラクティス
基本ルール
エンドポイントは必ず名詞（リソース名）で表現します。例: GET /v1/users、POST /v1/orders。操作はHTTPメソッドで表現し、URLに動詞を入れません。
複数形と一貫性
リソース名は基本的に複数形で統一します。/users、/productsのように統一すると理解しやすく、ルーティングも簡潔になります。
親子関係の表現
階層は親子関係で表現します。例: GET /v1/users/123/posts/456。IDはプレースホルダで表し、順序で関係を示します。
単語区切り・大文字・拡張子
単語はハイフン（-）で区切り、小文字のみで統一します。ファイル拡張子（.jsonなど）はURLに含めません。例: /v1/product-categories。
アクションとバージョン
特別な操作はなるべくサブリソースで表現します（例: POST /v1/users/123/activation）。APIのバージョンはパス先頭に含め、/v1/のようにします。
これらを守ると可読性・保守性が向上し、開発者間での共通理解が作れます。
URLパラメータ・クエリパラメータの使い方
パスパラメータ（URLパラメータ）の使い方
パス上のパラメータはリソースの一意識別に使います。例：GET /posts/123 はID 123 の投稿を取得します。必須項目を表すのに向いています。パスは短くわかりやすく保ち、階層で関係性を示します（/users/45/posts/10）。
クエリパラメータの使い方
検索、絞り込み、ページネーション、ソートなどの追加情報にはクエリを使います。例：GET /posts?author=123&sort=created_at&order=desc。パラメータはアンパサンド（&）で連結し、順序は問われません。
よく使うパターン
- ページング：?page=2&per_page=20
- ソート：?sort=created_at&order=desc
- フィルタ：?status=published&category=tech
- 配列：?tags=go,api または ?tags[]=go&tags[]=api と統一して扱います
実装上の注意
- URLには機密情報（パスワード、トークン）を置かないでください。ログやブラウザ履歴に残ります。
- 値は必ずURLエンコードして送信します（スペースや特殊文字対策）。
- クエリパラメータはキャッシュやCDNでキーになるので、一貫した命名を心がけます。
ドキュメント化とツール
パラメータの必須/任意、型、デフォルト値をAPIドキュメントで明確にします。ApidogのようなAPI管理ツールを使うと、パラメータ管理やリクエスト作成が効率化します。
まとめとなるポイント（簡潔に）
パスは「誰の」「どのリソース」かを示し、クエリは「どのように取得するか」を表します。扱いを明確に分けることで、検索性・保守性が向上します。
検索性・保守性・SEOを意識した設計
概要
APIのURLはシンプルで意味のある構造にします。読みやすさが高いほど検索性（人間が理解して検索しやすい）と保守性が向上します。
シンプルで意味あるパス
- リソース名は複数形で短く（例: /articles, /users）。
- 意味を持つパスを優先し、動詞を避ける（×/getUser → ○/users/{id}）。
命名と統一ルール
- 全プロジェクトで小文字・ハイフン区切りを採用します（例: /product-reviews）。
- クエリはフィルタやソート用、リソースの位置はパスで指定します。
バージョニング方針
- パスにバージョンを含めます（例: /v1/articles）。APIの互換性を保ちやすくなります。ヘッダーでのバージョン管理は別途検討します。
SEOを意識した設計
- 人が読めるURLを作ると検索で有利です。キーワードは過度に入れず自然な表現にします。
- ハイフンを使い、アンダースコアや大文字は避けます。拡張子は不要です。
保守性を高める運用
- 廃止時はバージョンとリダイレクトを用意し、互換性のある移行期間を設けます。
- ドキュメント・自動テスト・サンプルを整備して変更を追いやすくします。
具体例
良い: /v1/articles/2025/seo-tips
悪い: /getArticles.php?id=123&ver=1
API設計ドキュメント・ツールの活用
概要
API設計は文章だけで終わらせず、ドキュメントとツールで補完します。OpenAPI（旧Swagger）などで仕様を定義すると、設計、共有、テストが効率化します。
ドキュメント作成の基本
- 目的と利用者を明記します。例：外部開発者向け／社内サービス間通信。
- エンドポイント、メソッド、リクエスト/レスポンス例、ステータスコードを揃えます。
よく使うツールと機能
- OpenAPI/Swagger：仕様記述と自動生成の標準です。
- ドキュメント管理ツール（例：Apidog）：設計、ドキュメント自動生成、モック、テストを一元化します。
- 生成機能：クライアントSDK、サーバースタブ、APIテストコードを出力します。
実務での活用フロー
- 設計（OpenAPIで仕様を書き、例を添える）
- モックで挙動確認（フロントと並行開発可能）
- 実装と自動テスト（契約テストやCIで仕様順守を確認）
- SDKやドキュメントを自動配布
ベストプラクティス
- デザインファースト（仕様先行）を推奨します。早期に合意が取れます。
- サンプルを豊富に用意して誤解を減らします。
- バージョン管理と変更履歴を必ず残します。
注意点
- ドキュメントと実装が乖離すると信頼を失います。自動生成とテストで差分を減らしましょう。
- 過度に詳細すぎると読まれません。目的別に必要な情報を整理してください。
よくある落とし穴とアンチパターン
1. 動詞入りエンドポイント
エンドポイントに動詞を入れる例：/getUsers、/create-order。HTTPメソッドで操作を表現できるため、冗長で混乱を招きます。代替例：GET /users、POST /orders。
2. 冗長なパスやパラメータ
例：/users/list/all、/orders/123/details。不要な階層や重複パラメータは読みづらくなります。代替例：GET /users、GET /orders/123。
3. 命名の一貫性欠如
複数形と単数形の混在、スネークケースとケバブケースの混用は混乱を招きます。ポリシーを決めて全体で統一してください（例：/users、/user-profiles など）。
4. ファイル拡張子の混入
例：/users.jsonは不要です。Acceptヘッダで形式を扱い、URLはリソースに集中させましょう。
5. バージョン管理の不備
バージョンをURLに入れること自体は悪くありませんが、安易に破壊的変更を加えると互換性が壊れます。実装は明確にし、バージョンルールをドキュメントに残してください。
6. 過度なクエリ依存と複雑なフィルタ
1つのエンドポイントで全てを処理しようとすると理解しづらくなります。用途別にエンドポイントを分け、必要なフィルタだけを残しましょう。
7. エラーハンドリングの不統一
ステータスコードとエラーメッセージの形式を統一しないとクライアント実装が複雑になります。標準的な形式を定め、例外は明示してください。
まとめと実践ポイント
ここまでの内容を踏まえ、URL設計で重視すべき点と実践的なチェックリストを示します。
設計の原則
- リソースは名詞で、複数形を基本にします（例: /users）。
- 小文字とハイフンで単語を区切ります（例: /user-profiles）。
- 階層構造で関係を表現します（例: /users/{id}/posts）。
- 検索や絞り込みはクエリパラメータで行う（例: ?page=2&limit=20）。
- バージョンはURLかヘッダで明示します（例: /v1/users または Acceptヘッダ）。
- 動詞やファイル拡張子は使わないようにします。
実践チェックリスト
- まず命名ルールを決め、一貫して適用します。したがって設計段階で合意を取ります。
- シンプルさを優先し、冗長なパスを避けます。
- 将来の拡張を想定して階層とクエリを分けます。
- ドキュメントとテストを自動化して品質を保ちます。
ツールと運用
- OpenAPIで仕様を可視化し、Lintや自動生成で実装差異を減らします。
- APIゲートウェイやバージョニング戦略で互換性を管理します。
- 具体例をドキュメントに残し、開発者が参照できるようにします。
一貫性、シンプルさ、将来の拡張性を意識して設計してください。
