I'm working as a basic front desk, but when I was asked to design a RESTful API, I did a lot of research on the RESTful API. I thought about how to use path parameters, query parameters, and request bodies properly, so I would like to keep the results as a reminder. (It's pretty basic information, so it's for beginners.)
--Which of HTTP requests are path parameters, query parameters, and request body? ――What kind of information should be included in the path parameter, query parameter, and request body?
I will leave the explanation to this article. "HTTP Request" and "HTTP Response" / ITSakura
I will leave the explanation to this article. What is RESTful API / @ NagaokaKenichi
First, let's write about path parameters, query parameters, and what are request bodies.
Path parameters and query parameters are sent by URI.
https://example.com/pathparameter/{pathparameter}?queryparameter1=hogehoge&queryparameter2=fugafuga
As you can see from the example, After the domain in the URI? What comes before is the path parameter. And what comes after? Is the query parameter.
It's sent in JSON, not URI.
{
hoge_name: fugafuga,
description: hogefugahoge,
}
For example, it looks like this.
First, the path parameter, where you put ** the information needed to identify a particular resource **.
For example, suppose you have a table called group that bundles users like ↓, and you want to get users associated with a specific group (group 1) from there.
groups_table
| group_id | group_name | description |
|---|---|---|
| 1 | hoge | It is a group of hoge. |
| 2 | piyo | It is a group of piyo. |
users_table
| user_id | user_name | gruop_id | description |
|---|---|---|---|
| 1 | hoge | 1 | It belongs to the hoge group. |
| 2 | fuga | 1 | It belongs to the hoge group. |
| 3 | piyo | 1 | It belongs to the hoge group. |
| 4 | inu | 1 | It belongs to the hoge group. |
| 5 | neko | 2 | It belongs to the group of piyo. |
In this case, ** groupId = 1 ** is ** information required to identify a specific resource **, so the design and the API to actually hit are as follows.
design
https://example.com/groups/{group_id}
API to actually hit
https://example.com/groups/1
(I like the endpoint groups.)
Next, for query parameters, ** enter the information needed to manipulate and retrieve specific resources **.
Suppose you want to get 3 users associated with a specific group (Group 1) from the previous table in descending order of user_id.
In this case, the condition ** 3 cases ** and ** descending order of user_id ** is ** information required to operate and acquire a specific resource **, so the design and the API to actually hit are as follows. Become.
design
https://example.com/groups/{group_id}?sort=boolean&limit=number
API to actually hit
https://example.com/groups/1?sort=false&limit=3
(Sort is set so that ascending order is false and descending order is true.) Others seem to treat conditions related to ** search, filter **, etc. as query parameters.
Finally, regarding the request body, ** the content to be added or updated ** is entered here.
Suppose you want to update a specific group (Group 1) from the table above.
In this case, the condition of ** content to be updated ** is normal ** content when adding or updating **, so the design and the API to actually hit are as follows.
design(URI)
https://example.com/groups/{group_id}
design(JSON)
{
group_name: "string",
group_description: "string"
}
API to actually hit
https://example.com/groups/1
JSON to request
{
group_name: "hogehogehoge",
group_description: "hogehogehoge group"
}
-** Path parameters ** --After the domain with URI? The one who comes in front of -** Information needed to identify a particular resource ** -** Query parameters ** --The one that comes after? In the URI -** Information required to obtain by operating a specific resource ** -** Request body ** --The one that sends in JSON instead of URI -** Contents when adding or updating **
If you keep in mind like this, you may be able to design in an easy-to-understand manner. I'm reading O'Reilly Japan's Web API the GoodParts, so I may add it again if I read it.
Thank you for reading. I would be grateful if you could let me know if there are any misunderstandings!