事の発端

基本フロントのお仕事をしているのですが、RESTfulAPIの設計をしてね、と言われてRESTfulAPIについて色々調べることがありました。
パスパラメータ、クエリパラメータ、リクエストボディの使い分けについてヘ〜〜〜と思ったので、その結果を備忘として残したいと思います。
（かなり基礎的な情報なので、初心者向けです。）

この記事で書くこと

パスパラメータ、クエリパラメータ、リクエストボディってHTTPリクエストで言うどれのこと？
パスパラメータ、クエリパラメータ、リクエストボディにはどういう情報を持たせればいいの？

この記事で書かないこと(この記事を読む上での前提知識)

HTTPリクエストとは何か？

こちらの記事に説明を譲ります。
「HTTPリクエスト」と「HTTPレスポンス」 / ITSakuraさん

RESTful APIとは何か？

こちらの記事に説明を譲ります。
RESTful APIとは何なのか / @NagaokaKenichi さん　　

パスパラメータ、クエリパラメータ、リクエストボディってどれのこと？

まずパスパラメータ、クエリパラメータ、リクエストボディとは何かについて書いていきます。

パスパラメータ（Pathparameter）,クエリパラメータ(queryparameter)

URIで送るものがパスパラメータとクエリパラメータです。

https://example.com/pathparameter/{pathparameter}?queryparameter1=hogehoge&queryparameter2=fugafuga

例を見て貰えばわかるのですが、
URIでドメインの後、？の前に来るものがパスパラメータです。
そして、?の後に来るのがクエリパラメータです。

リクエストボディ(requestBody)

URIではなく、JSONで送るものです。

{
  hoge_name: fugafuga,
  description: hogefugahoge,
}

例えば、こんな感じになります。

パスパラメータ、クエリパラメータ、リクエストボディにはどういう情報を持たせればいいの？

パスパラメータ

まず、パスパラメータなのですが、ここには 特定のリソースを識別するために必要な情報 を入れます。

例えば↓のようなuserを束ねるgroupというテーブルがあり、そこから特定のグループ(グループ１)に紐づくユーザーを取得したいとします。

groups_table

group_id	group_name	description
1	hoge	hogeのグループです。
2	piyo	piyoのグループです。

users_table

user_id	user_name	gruop_id	description
1	hoge	1	hogeのグループに属しています。
2	fuga	1	hogeのグループに属しています。
3	piyo	1	hogeのグループに属しています。
4	inu	1	hogeのグループに属しています。
5	neko	2	piyoのグループに属しています。

この場合、groupId=１ は 特定のリソース識別するために必要な情報 なので設計と実際に叩くAPIは以下のようになります。

設計

https://example.com/groups/{group_id}

実際に叩くAPI

https://example.com/groups/1

(エンドポイントのgroupsについては好みです。)

クエリパラメータ

次に、クエリパラメータなのですが、ここには 特定のリソースを操作して取得する際に必要な情報 を入れます。

先ほどのテーブルから、特定のグループ(グループ１)に紐づくユーザーを3件、user_idの降順で取得したいとします。

この場合、3件と user_idの降順 という条件は 特定のリソースを操作して取得する際に必要な情報 なので設計と実際に叩くAPIは以下のようになります。

設計

https://example.com/groups/{group_id}?sort=boolean&limit=number

実際に叩くAPI

https://example.com/groups/1?sort=false&limit=3

（sortは昇順がfalse,降順がtrueという設定です。）
その他では、 検索、フィルタ などに関する条件がクエリパラメータとして扱われるようです。

リクエストボディ

最後に、リクエストボディなのですが、ここには 追加、更新する際の内容 を入れます。

先ほどのテーブルから、特定のグループ(グループ１)を更新したいとします。

この場合、更新する内容 という条件はまんま 追加、更新する際の内容 なので設計と実際に叩くAPIは以下のようになります。

設計(URI)

https://example.com/groups/{group_id}

設計(JSON)

{
  group_name: "string",
  group_description: "string"
}

実際に叩くAPI

https://example.com/groups/1

リクエストするJSON

{
  group_name: "hogehogehoge",
  group_description: "hogehogehogeのグループです"
}

まとめ

パスパラメータ
- URIでドメインの後、？の前に来るやつ
- 特定のリソースを識別するために必要な情報
クエリパラメータ
- URIで?の後に来るやつ
- 特定のリソース操作して取得する際に必要な情報
リクエストボディ
- URIではなく、JSONで送るやつ
- 追加、更新する際の内容

こんな感じで心がけるとわかりやすい設計ができるかもしれません。
オライリージャパンのWebAPI theGoodPartsを読み中なので読破したらまた付け加えるかもしれません。

読んでくださってありがとうございました。
認識違いなどありましたら教えてくださると嬉しいです！