What should be paid attention to when designing API to get data through post

More and more modern websites use front and back-end separation architecture , Use the front end first MVC The frame is piled up quickly SPA, Reuse API Getting dynamic data has become a daily development content ; And it's used to connect the front and back ends API, Its importance is also natural . As a front-end coder , Know the back end of API The design method is also very important , Let's aim at API Design to explore the .

HTTP Method

After all, it's the front and back of the website , Communication among them still depends on HTTP This stateless agreement ; stay HTTP A series of request methods are defined in the specification , The more commonly used ones are as follows ：

GET： Access to resources
HEAD： And GET Same as getting resources , But only get back Header
POST： Submit resources
PUT： Replace the specified resource
PATCH： Modify the specified resource
DELETE： Delete the specified resource
OPTION： Ask how to communicate with assigned resources

It is also mentioned in the specification , Different methods refer to different operations on the same thing , And through the semantic method , Different operations get different results .

Everyone to GET、POST No stranger , This is a HTML Of <form action="..."> Two methods supported ;GET It's the most frequently used , Whether it's getting pages or data , Generally used GET, and POST It is often used to add new resources , But because of HTML <form action="..."> No other methods are supported , In traditional websites, you may use POST Everything in the office except getting the data .

PUT and PATCH It's usually used to update resources , The difference between the two is PUT Is to replace the entire resource , and PATCH It is to update some resources ; If you put the two into everyday life , It's like eating in a restaurant , The whole table is ordered again PUT, In addition, the dishes are PATCH.

DELETE Usually used to delete resources ;HEAD And GET similar , But only get back Header, It is usually used to test whether a resource exists ;OPTION It's asking how to get this resource , Usually used for sending CORS Pre inspection of （preflight） request .

At present, we are talking about the general usage mentioned and suggested in the specification , Of the actual server API How to develop still depends on the implementation of people ; But design by means of semantics API, You can definitely make API More developer friendly .

RESTFul API

What I said earlier is just specification , And it only involves HTTP Method ; Is there a more complete implementation method ？

Of course. , That's what you hear all the time RESTFul API; It consists of Roy Fieldin stay IEFT Development HTTP Standard six-year continuous research 、 Verified , And in 2000 In his doctoral thesis 《Architectural Styles and the Design of Network-based Software Architectures》 Proposed in , It's a design style of network program ; So-called REST yes Presentation layer state transition （Resource Representational State Transfer） Abbreviation , In short, it is through the verb （HTTP Method ）、 Noun （URI/URL, Represents the target resource ）、 Content type （ The content of the response , Such as HTML、XML、JSON etc. ）, Let stateless network communication pass through REST Semantic design of , Carry all the States to communicate , Reduce the resource consumption caused by repeated requests to the network .

For example, suppose you have a video site ：myku.com, It's the API It's possible that's going to be the way ：

[GET] http://myku.com/v1/videos/ ->  obtain  video  list 
[POST] http://myku.com/v1/videos/->  newly added  video
[GET] http://myku.com/v1/videos/MgphHyGgeQU ->  Get specified  ID  Of  video
[PUT] http://myku.com/v1/videos/MgphHyGgeQU ->  Modify designation  ID  Of  video
[DELETE] http://myku.com/v1/videos/MgphHyGgeQU ->  Delete specified  ID  Of  video

In addition to the methods used , We should also pay attention to the resource representation URL The way of writing , No HTTP The method is consistent with the actual action RESTful API ！

alike ,RESTFul API It's just design style, not HTTP The specification of , It is likely that the design will be based on RESTful The spirit of , But the result of actual development is not RESTful Style ; But there's no denying that through RESTful API Design style of , Each resource will get a corresponding location （URL）, And can pass HTTP The method of semantic , Interact with assigned resources , Overall resource management will become very semantic and clear , This is really an excellent one API design methods .

Specification and Implementation

stay HTTP The specification mentions how to use the method correctly , If we don't implement it according to the specification , It will have a certain impact .

cache

The browser defaults to GET、HEAD These two methods are cached , If you pass POST instead of GET If you get resources , Browsers and proxy servers in the middle generally do not implement caching mechanism , In this case, the front and back-end developers must set up the cache by other means .

Although it is also mentioned in the specification POST stay Header You can also cache when appropriate , But in fact, it's common to put POST Used for adding operations , Caching can cause unexpected consequences , Most browsers don't implement it for POST Cache mechanism .

SEO

When search engine crawlers are scanning websites , If it is found that it needs to pass POST Resources obtained , In order to avoid unexpected behavior or side effects , Usually, you don't try to crawl POST The result of the response .

GraphQL

although RESTful API There are many advantages to the design style of , But there are also some unavoidable shortcomings .

For example, when looking for nested data with dependencies , It's very likely that you have to ask many times to find the desired result ; And as the project architecture expands , Information on the same page will become more and more complex , You may need data from multiple sources to pile up pages , Now RESTful API You need to describe the characteristics of each resource location , Will make RESTful API It doesn't seem to be very useful ; And because mobile devices are so popular now , A back-end server may need to serve PC Page 、 mobile phone APP Wait for the demand of many equipment , The data needed may be different ,RESTful API It is necessary to implement multiple interfaces with similar functions ,API It's going to get bigger and bigger , It's relatively difficult to manage .

If there is a need, there will be a solution . At this time GraphQL And that's what happened , This is from Facebook Proposed open source language standard , adopt Schema Defining data , Rely on and JSON Highly similar format query statements get the results of the query , Its main feature is ：

Strong type
Query statement is file
The query statement is the data structure of the response , There will be no redundant content
A unified external entrance
You can query and merge more , Back together

These features effectively solve RESTful API Problems in a complex architecture , send GraphQL Full of flexibility 、 Very easy to use , Communities also have huge ecosystem support , for example Apollo GraphQL It can be deeply integrated with the three frameworks , Plus the multi query merge feature , Give Way GraphQL It fits perfectly with the concept of components in modern frameworks .

The disadvantage is that all the complex data splicing logic must be implemented in the back end , To be used to RESTful API For the developers , It costs a lot of learning .

It is worth noting that GraphQL All that was sent out was POST request , The caching mechanism must depend on the developer or the framework implementation ; For example, in Apollo Client in , Developers must follow the application scenario , adjustment fetchPolicy Set up , Avoid the unexpected results of caching .

Postscript

The title of this article is an interview question when a friend of mine went to interview the back end of a large factory , From this subject HTTP Methods and mainstream RESTful API Design style , Also on GraphQL A brief introduction was made , I hope the above can help you .