[RESTful API] Differences and design of path parameters, query parameters, request body

The beginning of the matter

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.)

What to write in this article

--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?

Do not write in this article (prerequisite knowledge for reading this article)

What is an HTTP request?

I will leave the explanation to this article. "HTTP Request" and "HTTP Response" / ITSakura

What is the RESTful API?

I will leave the explanation to this article. What is RESTful API / @ NagaokaKenichi

What are path parameters, query parameters, and request bodies?

First, let's write about path parameters, query parameters, and what are request bodies.

Path parameter, query parameter

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.

Request Body

It's sent in JSON, not URI.

{
  hoge_name: fugafuga,
  description: hogefugahoge,
}

For example, it looks like this.

What kind of information should be included in the path parameter, query parameter, and request body?

Path parameters

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.)

Query parameters

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.

Request body

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"
}

Summary

-** 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!

Recommended Posts

[RESTful API] Differences and design of path parameters, query parameters, request body
The design concept of Java's Date and Time API is interesting
[Rails] Differences and usage of each_with_index and each.with_index