Since there is a lot of best practice content related to network requests, it will be split into three articles, namely:
- Previous article: Request specifications
- Part 2: Cookie, Session and input parameter verification
- Next article: Integration and use of browser plug-ins
Welcome to follow the WeChat public account “Silent Station” to get the latest sharing.
Let’s enter the main text of this article. The best practices for request specifications will be introduced in three parts:
- Why is a request specification needed?
- Why not just use Restful/GraphQL?
- FaasJS request specification
Why do we need a request specification?
Network requests have multi-layer protocol specifications, but at the final application layer, due to differences in business forms and other differences, there are no mandatory specification constraints, which makes it highly flexible, and improper use can also cause serious confusion.
Therefore, usually each company will customize its own internal and external communication request specifications to reduce communication costs and development costs through specifications.
Why not just use Restful/GraphQL?
Let’s look at these two specifications separately.
Restful is currently a widely popular request specification. It uses request method as a verb and request path as a noun. It maps business logic to operations on resources, which is very close to object-oriented design ideas.
But it has two disadvantages:
- The types of HTTP methods are fixed and are not fully applicable to business logic. On the one hand, some businesses are difficult to abstract into a certain HTTP method; on the other hand, the semantics of PUT and PATCH are easily confused;
- Split the business logic into individual resources. In some scenarios, the split will be too detailed and difficult to understand (such as mapping login behavior to POST /sessions).
In the context of front-end and back-end separation, GraphQL gives front-end development very high flexibility, and its Query / Mutation separation method also well distinguishes between querying and modifying data. I personally think that GraphQL is currently the best specification in non-Serverless scenarios.
But in the Serverless scenario, because Serverless is naturally suitable as a BFF layer (even for smaller businesses, Serverless can be used completely as the backend), front-end development can also have enough flexibility to create and modify APIs by themselves.
At the same time, in the Serverless scenario, since the request entry of GraphQL is single, this requires high stability of the entry cloud function. When it is unavailable, all interfaces may be unavailable.
FaasJS request specification
In FaasJS, the advantages of Restful and GraphQL are combined, and a set of simple and intuitive request specifications is formed according to the characteristics of cloud functions.
Its provisions are as follows:
- The request method is unified into POST method
- The request path is the file path of the cloud function in the project
- Request parameters are uniformly placed in the Body in JSON format
- Responses are uniformly returned as JSON
- The response content of a successful operation is wrapped in the data field
- The failure reason for operation failure is wrapped in the error field
The internal logic of this request specification is: first organize the cloud functions, and then directly map them to APIs.
In FaasJS, folders are used as a natural isolation method to distinguish and place cloud functions under different businesses. After being mapped to an API, this intuition also conveys the API level.
In addition, for the browser, although we use the POST method, you can add a cache header such as “Cache-Control” in the response header to tell the browser to cache. In some scenarios with complex query conditions, there is no need to worry about too many query conditions reaching the browser GET request length limit.
Finally, you are welcome to follow the public account “Silent Station” and communicate and discuss with me.