I was entrusted with the design of the back end, so let's learn the endpoint design firmly

Introduction

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.

Let's start endpoint design!

I think there is no problem with the recognition that it is a URI ** for accessing the API.

basic way of thinking

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.

[1] Can be read and understood by a third party

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

[2] Basically use all lowercase letters

It is easier to understand if you unify to either one, so mistakes will be reduced.

[3] Be consistent with other endpoints

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.

Relationship between HTTP methods and endpoints

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

Actually design the endpoint

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 individual data

GET /members/:id

It is an image that the set data called members is specified by id. Basically, this shape is common.

Get the whole

GET /members

We are getting all the information of members. Search etc. is an image controlled by the query parameter in this endpoint.

New data creation

POST /members

This time id is not specified. Since this is a POST method, it comes from ** creating new data that depends on members **.

Data update

PUT /members/:id

In the update, id information is given to specify the member to actually update.

Delete data

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

I was entrusted with the design of the back end, so let's learn the endpoint design firmly
I was stuck with the handling of the time zone when formatting with SimpleDateFormat
I checked the number of taxis with Ruby
When creating the top page, I was stuck with the handling of images (super beginner)
I was addicted to the record of the associated model