Restful interface specification

Time:2022-1-10

Rest interface specification
1. Action
Get (select): retrieves a specific resource, or list of resources, from the server.
Post (create): create a new resource on the server.
Put (update): updates the resources on the server and provides the entire resource.
Patch (update): updates the resources on the server, providing only the changed attributes.
Delete (delete): deletes resources from the server.
The first is four and a half actions:
post、delete、put/patch、get
Because put / patch can only be counted as one category, patch is classified as half.
There are also two less well-known HTTP verbs:
Head – retrieves metadata about the resource, such as the hash of the data or the last update time.
Options – retrieves information about what the client is allowed to do with the resource.
2. Path (interface naming)
The path, also known as “endpoint”, represents the specific web address of the API.
In the restful architecture, each web address represents a resource, so there can be no verbs but only nouns in the web address, and the nouns often correspond to the table name of the database. Generally speaking, the tables in the database are “collections” of the same kind of records, so nouns in the API should also be plural.
For example, if there is an API that provides zoo information, including information about various animals and employees, its path should be designed as follows.
Try to use nouns instead of verbs in the interface. Here are some examples.

Get / zoos: list all zoos
Post / zoos: create a new zoo
Get / zoos / ID: get the information of a specified zoo
Put / zoos / ID: update the information of a designated Zoo (provide all the information of the zoo)
Patch / zoos / ID: update the information of a specified Zoo (provide some information of the zoo)
Delete / zoos / ID: delete a zoo
Get / zoos / ID / animals: lists all animals in a specified zoo
Delete / zoos / ID / animals / ID: deletes the specified animals in a specified zoo
Counterexample:
/getAllCars
/createNewCar
/deleteAllRedCars
For another example, a URI is / posts / show / 1, where show is a verb. The URI is designed incorrectly. The correct way to write it should be / posts / 1, and then use the get method to represent show.
If some actions cannot be represented by HTTP verbs, you should turn the actions into a resource. For example, for online remittance, 500 yuan is remitted from account 1 to account 2. The wrong URI is:
POST /accounts/1/transfer/500/to/2
The correct way to write it is to change the verb transfer into the noun transaction. A resource cannot be a verb, but it can be a service:
POST /transaction HTTP/1.1
  Host: 127.0.0.1
  from=1&to=2&amount=500.00
  
Clarify the hierarchical structure of resources. For example, if the business is aimed at schools, schools will be primary resources (/ school / teachers), and students (/ school / students) will be secondary resources.
3. Versioning
The version number of the API should be placed in the URL. For example:
https://api.example.com/v1/
Another way is to put the version number in the HTTP header, but it is not as convenient and intuitive as putting it in the URL. GitHub adopts this approach.
4. Filtering
If the number of records is large, the server cannot return them to the user. The API should provide parameters to filter the returned results.
Here are some common parameters.

? Limit = 10: Specifies the number of returned records
? Offset = 10: Specifies the start position of the return record.
? page_ number=2&page_ Size = 100: specify the page number and the number of records per page.
? Sortby = name & order = ASC: specify which attribute to sort the returned results and the sort order.
? animal_ type_ Id = 1: specify filter criteria
The design of parameters allows redundancy, that is, occasional duplication of API path and URL parameters. For example,
Get / Zoo / ID / animals and get / animals? zoo_ Id = ID has the same meaning.

5. Status codes
Status code range

1XX message, request received, continue processing. Scope keeps things for the underlying HTTP that you probably never use.
2XX success, behavior is successfully accepted, understood and adopted
3xx redirection is an action that must be performed further in order to complete the request
4xx client error, the request contains syntax error or the request cannot be implemented. Scope reservation is used to respond to errors made by the client, for example. They provide bad data or ask for something that doesn't exist. These requests should be idempotent, not change the state of the server.
The status code in the 5xx range is reserved for server-side errors. These errors are often thrown from the underlying functions, or even
Developers usually can't handle it. The purpose of sending such status codes is to ensure that the client gets some response.
When receiving a 5xx response, the client cannot know the status of the server, so such status codes should be avoided as much as possible.

The status code and prompt information returned by the server to the user are common as follows (the HTTP verb corresponding to the status code is in square brackets).

200 OK - [get]: the server successfully returns the data requested by the user. The operation is idempotent.
201 created - [post / put / patch]: the user successfully creates or modifies data.
202 accepted - [*]: indicates that a request has entered the background queue (asynchronous task)
204 no content - [delete]: the user successfully deleted the data.
400 invalid request - [post / put / patch]: there is an error in the request sent by the user. The server does not create or modify data. The operation is idempotent.
401 unauthorized - [*]: indicates that the user does not have permission (wrong token, user name and password).
403 Forbidden - [*] indicates that the user is authorized (as opposed to 401 error), but access is prohibited.
404 Not Found - [*]: the request sent by the user is for a nonexistent record. The server does not operate. The operation is idempotent.
406 not acceptable - [get]: the format of the user request is not available (for example, the user requests JSON format, but only XML format).
410 gone - [get]: the resource requested by the user is permanently deleted and will not be obtained again.
422 unprocessable entity - [post / put / patch] a validation error occurs when an object is created.
500 international server error - [*]: if an error occurs in the server, the user will not be able to judge whether the issued request is successful.
502 gateway error
503 Service Unavailable
504 gateway timeout