Restful APIにおける子リソースのAPIのパス設計

Question

Restful APIで親リソースを指定した子リソースの指定方法はどのようにするべきでしょうか？

DBは以下の2つのような構造をもつモデルとなっています。
子のChildモデルは親のParentモデルのIDを知っています。

• Parent model

{
  id: 42142141,
}

• Child model

{
  id: 24214121,
  parent_id: 42142141
}

その時、子のモデルを親のIDから取得したいとします。
私の中ではどちらの指定方法がよろしいのでしょうか？

1. パスに指定する方法

/api/v1/parents/42142141/children

2 クエリパラメターに指定する方法

/api/v1/children?parent_id=42142141

エンティティは親子関係を持っていますので、パスで指定するのも悪くないですし、
子のエンティティは親のIDを知っていますので、クエリパラメータでしていするのも悪くないと思います。

どちらが良いかご指導よろしくお願いします。

Answer 1

クエリパラメータで指定するパターンの場合、一覧(GET)、詳細(GET)、新規作成入力(GET)、編集入力(GET)はいいのですが、追加(POST)、更新(PUT)、削除(DELETE)といったGET以外のメソッドのときにクエリパラメータが付くという気持ち悪いURLになるので、私は前者のパスに指定する方を取ります。

Answer 2

こういった時にだいたいteratail APIを引き合いに出すのですが、teratail APIでは同様の状況、例えば特定のユーザーのフォロワーを取得するというAPIではエンドポイントは下記のように定義されます。display_nameがパラメータです。

https://teratail.com/api/v1/users/**__display_name__**/followers

ですので、「1.パスに指定する方法」の方を採用しているようです。
ご参考まで。