はじめに
「REST APIのURLは、どんなルールで決めればいいの？」
「ユーザー情報の取得や更新で、URLを分けるべきか迷う」と感じていませんか。
APIを新しく設計するとき、同じデータを扱う場合でもURLの付け方には複数の候補があり、どれを選べば実装後も管理しやすいのか判断に迷いますよね。
この記事では、REST APIのURL設計で押さえたい基本ルールから、単数形・複数形、階層構造、クエリパラメータなど迷いやすいポイントの判断基準まで、順を追って説明していきます。
REST APIのURL設計で押さえる基本ルール
REST APIのURLは、利用者が見たときにどのリソースを対象としているのか判断できる形にそろえることが重要です。
ここでは、REST APIのURLを設計するときに押さえておきたい基本ルールを順に説明します。
URLはリソースを名詞で表す
REST APIのURLには、処理内容ではなく操作するリソースを名詞で指定します。
たとえばユーザーなら「/users」のように、URLを見ただけで何を扱うのか分かる名称にしましょう。
「/getUsers」のように操作を含めないのが基本です。
リソース名は複数形で統一する
リソース名は「/users」や「/products」のように、複数形で統一すると分かりやすくなります。
1件を指定する場合も「/users/123」のように識別子を付け、「/user」と「/users」が混在しないようにしましょう。
小文字と分かりやすい英単語で命名を統一する
リソース名は小文字で統一し、「/users」「/orders」のように内容が伝わる英単語を使います。
「/Users」と「/users」が混在しないよう、API全体で同じルールを決めておくと管理しやすくなります。
URLに動詞を入れず操作はHTTPメソッドで表す
取得・作成・更新・削除などの操作はURLに含めず、HTTPメソッドで表します。
たとえば「/users」に対して、取得はGET、作成はPOSTのように使い分けると、URLをシンプルに整理できます。
REST APIのURLとHTTPメソッドの役割分担
REST APIでは、URLで操作内容まで表すのではなく、URLとHTTPメソッドの役割を分けて設計します。
ここでは、同じURLをHTTPメソッドで使い分ける方法と、操作ごとにURLを増やさない考え方を説明します。
同じURLをGET・POST・PUT・PATCH・DELETEで使い分ける
同じリソースへの操作はURLを変えず、HTTPメソッドで区別します。
たとえば「/users」に対して、取得はGET、作成はPOST、更新はPUT・PATCH、削除はDELETEのように使い分けます。
PUTとPATCHはどちらも更新に使うため、実際のAPI設計でどちらを選べばよいか迷う場合は、違いを確認しておくと判断しやすくなります。
▶REST APIのPUTとPATCHの違いとは？使い分けをわかりやすく解説
操作ごとにURLを増やさない
「/getUsers」や「/createUser」のように、操作ごとにURLを作る必要はありません。
同じリソースならURLを共通にし、操作はHTTPメソッドで分けることで、エンドポイントを分かりやすく整理できます。
REST APIのURLでリソースをネストする方法
REST APIでは、リソース同士に親子関係がある場合、URLを階層化して関係性を表現できます。
ここでは、親子関係をネストで表す方法と、トップレベルに分ける判断基準、URLの階層を深くしすぎない設計について説明します。
親子関係があるリソースはネストで表現する
親リソースに属する子リソースは、URLをネストして関係を表します。
たとえば、ユーザー「123」の注文なら「/users/123/orders」とすることで、どのユーザーに属するデータなのか分かりやすくなります。
単独で扱えるリソースはトップレベルも検討する
親リソースを経由しなくても対象を特定できる場合は、トップレベルのURLも検討します。
たとえば、注文IDだけで特定できるなら「/orders/456」とすることで、シンプルなURLで扱えます。
URLの階層を深くしすぎない
ネストを重ねるとURLが長くなり、構造も分かりにくくなります。
親リソースを省いても対象を特定できる場合はトップレベルに分けるなど、必要以上に階層を深くしないようにしましょう。
PathとQueryパラメータの使い分け
REST APIのURLでは、指定する情報の役割に応じてPathとQueryパラメータを使い分けます。
ここでは、PathとQueryパラメータをどのような基準で使い分けるのかを説明します。
特定のリソースを指定するときはPathを使う
特定のリソースを指定する場合は、URLのPathに識別子を含めます。
たとえば、IDが「123」のユーザーなら「/users/123」のように表し、操作する対象を一意に指定します。
検索・絞り込みにはQueryを使う
複数のリソースから条件に合うデータを探す場合は、Queryパラメータを使います。
たとえば「/users?status=active」のように指定すると、対象を変えずに取得条件を追加できます。
Queryパラメータの付け方や複数条件の指定方法まで確認したい場合は、具体的な書き方もあわせて確認しておくと安心です。
▶URLのクエリパラメータとは？書き方と複数指定の方法を解説
ソート・ページネーションはQueryで表現する
並び順や取得範囲を指定する場合も、Queryパラメータを使います。
たとえば「/users?sort=created_at」で並び順を指定し、「/users?page=2&limit=20」のようにページ番号や取得件数を設定します。
REST APIのURLにバージョンを付ける方法
REST APIでは、仕様変更による既存の利用者への影響を抑えるため、APIのバージョンを分けて管理することがあります。
ここでは、URLへバージョンを含める方法と、バージョンを分けるタイミングについて説明します。
「/v1/」のようにURLへバージョンを含める
APIのバージョンをURLで管理する場合は、「/v1/users」のようにPathへ番号を含めます。
仕様変更で新しいバージョンを提供するときは「/v2/users」とすることで、利用するAPIの仕様をURLから判別できます。
APIの仕様変更を予定していて、どの変更でバージョンを分けるべきか迷う場合は、バージョニングの考え方も確認しておきましょう。
▶REST APIのバージョニングとは？v1・v2の付け方と変更タイミングを解説
互換性を壊す変更をするときにバージョンを分ける
既存のクライアントがそのまま利用できない変更を行う場合は、新しいバージョンへ分けます。
リクエスト項目の削除やレスポンス構造の変更などが該当し、互換性を保てる修正であれば、変更のたびにバージョンを増やす必要はありません。
REST APIのURL設計のOK・NG例
REST APIのURL設計では、基本ルールを理解していても、実際のエンドポイントに当てはめると判断に迷うケースがあります。
ここでは、代表的なURLを比較しながら、避けたい設計と修正方法を説明します。
リソースを名詞で表したURLと動詞を含むURL
ユーザーを取得する場合、OK例は「GET /users」、NG例は「GET /getUsers」です。
取得の操作はGETで表せるため、URLには動詞を含めず「/users」のようにリソースを名詞で指定します。
ネストが適切なURLと階層が深すぎるURL
特定のユーザーに属する注文なら「/users/123/orders」のように表します。
一方、「/users/123/accounts/456/orders/789/items」のように階層が深くなる場合は、親リソースを省いても対象を特定できないか確認しましょう。
PathとQueryを適切に使い分けたURL
特定のユーザーなら「/users/123」のようにPathを使い、条件で絞り込む場合は「/users?status=active」のようにQueryを使います。
リソースを特定する値なのか、検索条件なのかを基準に使い分けると分かりやすくなります。
用途ごとにエンドポイントを増やしすぎたURL
「/getUsers」「/createUser」「/deleteUser」のように、操作ごとにURLを分ける必要はありません。
同じユーザーを扱う場合は「/users」に統一し、GET・POST・DELETEなどのHTTPメソッドで操作を区別します。
REST APIのURL設計で迷ったときの判断基準
REST APIのURL設計で複数の候補がある場合は、まずURLが何のリソースを扱うのかを明確にします。
ここでは、REST APIのURL設計で迷ったときに確認したい判断基準を順に説明します。
まず「何のリソースを扱うURLか」を決める
URLを決めるときは、まず何のリソースを扱うのかを明確にします。
ユーザーなら「/users」、注文なら「/orders」のように、操作内容ではなく対象となるリソースを名詞で表しましょう。
操作はHTTPメソッドで表現できないか確認する
取得はGET、作成はPOST、更新はPUT・PATCH、削除はDELETEのように、操作はHTTPメソッドで表します。
HTTPメソッドで区別できる場合は、「get」や「delete」などを含むURLを別に作る必要はありません。
別URLを作る前にPathやQueryで表現できないか確認する
別のURLを作る前に、PathやQueryで表現できないか確認します。
特定のユーザーなら「/users/123」、条件で絞り込むなら「/users?status=active」のように、目的に合わせて使い分けましょう。
命名ルールを決めてチーム内で統一する
URLの命名ルールは、あらかじめチーム内で決めておくと管理しやすくなります。
リソース名は複数形、英字は小文字などの基準を設け、すべてのエンドポイントで表記をそろえましょう。
まとめ
REST APIのURL設計では、扱うリソースを名詞で表し、操作はGET・POST・PUT・PATCH・DELETEなどのHTTPメソッドで分けるのが基本です。
PathやQueryも役割に合わせて使い分け、命名ルールを統一しておくと、エンドポイントが増えても分かりやすい設計を保ちやすくなります。
設計に迷ったときは、まず「何のリソースを扱うURLなのか」を整理し、HTTPメソッドやPath・Queryで表現できるかを順番に確認してみましょう。
基本的なルールを揃えておくことで、あとから見ても理解しやすく、管理しやすいREST APIにつながります。
