APIのURLとして以下のどちらが適切か
判断基準について
以下2点をもとにどちらで表現するか判断すると良い。
-
一意なリソースを表すのに必要かどうか
⇛パスパラメータを利用 -
省略可能かどうか
⇛クエリパラメタを利用
ユースケース
GET
GET https://api.hoge.com/users?id=12345
GET https://api.hoge.com/users/12345
この場合、ユーザIDは省略可能（全ユーザを取得可能）なので、クエリパラメタでの表現が適切。
○ GET https://api.hoge.com/users?id=12345
POST
POST https://api.hoge.com/users?id=12345
POST https://api.hoge.com/users/12345
POST https://api.hoge.com/users（bodyで指定）
この場合、ユーザIDを省略することは出来ないので、パスでの指定か、bodyでの指定が適切。
厳密には、POST時にusersという集合の中にユーザ12345はまだ存在しておらず指定出来ないので、
POST https://api.hoge.com/users（bodyで指定）
がbetterか。
PUT
PUT https://api.hoge.com/users?id=12345
PUT https://api.hoge.com/users/12345
PUT https://api.hoge.com/users（bodyで指定）
この場合、ユーザIDを省略することは出来ないので、パスでの指定か、bodyでの指定が適切。
/usersという指定だと、users全体の集合をbodyに入れて集合全体更新するようなイメージもあるので、
明確に1ユーザ更新のAPIの場合、
PUT https://api.hoge.com/users/12345
がbetterか。
まとめ
一般論でのbetterはこんな感じになるが、
一方で、更新系に関しては要件に依るところも大きく、APIごとに設計が分かれるところ。
GET https://api.hoge.com/users?id=12345
POST https://api.hoge.com/users（bodyで指定）
PUT https://api.hoge.com/users/12345
たとえば、複数ユーザの一括登録、一括更新をしたい場合に、
パス指定だと対応出来ないため、以下のような設計にしたとする。
GET https://api.hoge.com/users?id=12345
POST https://api.hoge.com/users（bodyで指定）・・・Nユーザ対応可能（N≧1)
PUT https://api.hoge.com/users/12345 ・・・1ユーザ対応可能
PUT https://api.hoge.com/users（bodyで指定） ・・・Nユーザ対応可能（N≧1)
そうすると下から二つ目は冗長なので、それなら最初から以下のように設計した方が良い。
GET https://api.hoge.com/users?id=12345
POST https://api.hoge.com/users（bodyで指定）・・・Nユーザ対応可能（N≧1)
PUT https://api.hoge.com/users（bodyで指定） ・・・Nユーザ対応可能（N≧1)
そのため、原則を踏まえて、API全体設計の整合やリクエスト要件を踏まえた上で、
それぞれ設計するのが良い。