Hello, has worked as a Web engineer at startup taken a leave of absence from the university is Onikan.
I was entrusted with the endpoint design of the project I am currently involved in, so I thought it was a good opportunity, so I studied from ** 1 and summarized it. ** If you have any suggestions, I would appreciate it if you could comment.
I think there is no problem with the recognition that it is a URI ** for accessing the API.
The URI design should be ** "simple and straightforward" **. Why is a "simple and easy-to-understand" URI good? The main reason is that "it can reduce developer mistakes". For example, which of the following two URIs is easier to understand?
api/v1/p/c
api/v1/posts/comments
The former is difficult to understand because only the acronym is reflected in the URI. On the other hand, you can imagine that the latter is a resource for comments in a certain post. By making the URI easy to understand, you can reduce developer mistakes and improve the quality of service as a result.
In order to make the URI design "simple and easy to understand", I have summarized specific tips from the following.
api/v1/p/c
It's hard to predict what an endpoint like the one above shows. In the above cases, it is kinder to at least clearly indicate the resources as shown below.
api/v1/posts/comments
It is easier to understand if you unify to either one, so mistakes will be reduced.
For example, the following endpoints are inconsistent. (Although a little strange)
api/v1/posts/:id
api/v1/friends/?id=1
The above is an extreme example, but I think it is easier to understand if the format is unified as much as possible as shown below.
api/v1/posts/:id
api/v1/friends/:id
Basically, these three are important. In more detail
--URLs that are easy to change --URLs where the server architecture is difficult to understand
What a place, such as.
The URI and HTTP methods each have the following roles.
** URI: Resource (information) ** ** HTTP method: behavior **
In other words, URI (information) can be manipulated by HTTP method. For example, the HTTP method GET stands for" get ".
GET api/v1/posts/100
Then, ** You can get (operate) data (resource) with Post ID of 100 **
** The important thing is that the URI and HTTP methods are separate **. It is not recommended to specify the behavior (for example, get or delete) in the URI, nor is it recommended that HTTP methods invade the resource area.
I will briefly explain the main HTTP methods from the following.
GET
The GET method indicates ** "get" **. Gets the resource specified by the URI and returns it to the client. The following is an example.
GET api/v1/posts/100
The important thing is that the content of "information (resource)" must not be changed by the ** GET method **. If you want to create a resource, you should basically use the Post, update it with PUT or PATCH, and delete it with the DELETE method.
POST
The POST method indicates ** "Create" **. In other words, ** "Send resources belonging to the specified URI" **. Let's look at an example
POST api/v1/posts
You can see that the id specification that was at the time of GET has disappeared. In other words, resources are created in a form that belongs to Posts. Basically, POST should be used for ** "new" **, and if you want to do something with an existing resource, you should use PUT or DELETE.
PUT
The PUT method is used when the information is "updated". The PUT method, unlike POST, ** specifies the URI you want to update. ** The following is an example. (Actually, data is specified by query parameter, but this time it is omitted)
PUT api/v1/posts/100
Unlike the POST method, you can see that it is specified directly. (POST creates subordinate resources.) By the way, if the specified resource does not exist, the resource will be created. However, you should basically use the POST method to create a resource.
DELETE
The DELETE method "deletes" the resource with the specified URI.
DELETE api/v1/posts/100
PATCH
The PATCH method has the role of "update" like PUT, but it does not update all the information, but some information.
That's it for the HTTP method. From now on, I would like to design a concrete endpoint by combining ** URI and HTTP method. ** **
We've looked at basic resources and HTTP methods. Let's actually combine the two from here!
This time, let's consider the endpoint for the data model member.
GET /members/:id
It is an image that the set data called members is specified by id. Basically, this shape is common.
GET /members
We are getting all the information of members. Search etc. is an image controlled by the query parameter in this endpoint.
POST /members
This time id is not specified. Since this is a POST method, it comes from ** creating new data that depends on members **.
PUT /members/:id
In the update, id information is given to specify the member to actually update.
DELETE /members/:id
In the case of deletion, member is specified in the same way, so id information is given.
That's the basic part. After that, I think it's better to get feedback in the actual battle.
See you soon~
Recommended Posts