1, Introduction

REST, namely Representational State Transfer, is a software architecture style. It is a design and development method for network applications, which can reduce the complexity of development and improve the scalability of the system.

REST refers to a set of architectural constraints and principles. Applications or designs that meet these constraints and principles are RESTful.

2, URI

The URI represents the resource, which generally corresponds to the entity class in the server-side domain model.

URI specification

1. Do not use capital letters;
2. Use the middle bar - do not use the lower bar;
3. The parameter list should be encode d;
4. Nouns in URI s represent collections of resources and are plural.

Examples

GET    /zoos: List all zoos
POST   /zoos: Build a new zoo
GET    /zoos/ID: Get information about 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 designated Zoo (provide some information of the zoo)
DELETE /zoos/ID: Delete a zoo
GET    /zoos/ID/animals: List all animals in a designated zoo
DELETE /zoos/ID/animals/ID: Delete a designated animal in a designated Zoo

/The hierarchy is expressed in the url, which is used for object navigation according to the entity association relationship, generally according to the id.

Too deep navigation is easy to cause url expansion and difficult to maintain, such as GET /zoos/1/areas/3/animals/4. Try to use query parameters instead of entity navigation in the path, such as get / animals? zoo=1&area=3；

Filtering

?limit=10: Specifies the number of records returned
?offset=10: Specifies the start position of the return record.
?page=2&per_page=100: Specify the page number and the number of records per page.
?sortby=name&order=asc: Specify which attribute to sort the returned results by and the sort order.
?animal_type_id=1: Specify filter criteria

RESTful API that does not comply with CRUD

In the actual resource operation, there will always be some cases that do not comply with CRUD (create read update delete). Generally, there are several processing methods.

1. Use POST to add an endpoint for the required action. Use POST to perform the action, such as POST /resend to resend the email.

2. Control by adding action parameters. For example, a blog website will have the function of "publishing" a written article. You can use the above POST /articles/{:id}/publish method, or add the published:boolean field in the article. When publishing, update the field PUT /articles/{:id}?published=true

3. github uses this method to convert actions into resources and actions into resources that can perform CRUD operations.

For example, to "like" a gist, add a / gists/:id/star sub resource, and then operate it: "like" use PUT /gists/:id/star, "Cancel" use DELETE /gists/:id/star.

Another example is fork, which is also an action, but by adding forks resources under gist, the action can become CRUD compatible: POST /gists/:id/forks can execute the action of user fork.

3, Http method

4, Http response

summary

The server must respond to every request from the client. The response includes HTTP status code and data.

HTTP status code is a three digit number, which is divided into five categories.

1xx: Relevant information
2xx: Operation successful
3xx: redirect
4xx: Client error
5xx: Server error

Status code

1xx status code

The API does not require a 1xx status code

2xx status code

The 200 status code indicates that the operation is successful, but different methods can return a more accurate status code.

GET:    200 OK
POST:   201 Created
PUT:    200 OK
PATCH:  200 OK
DELETE: 204 No Content

3xx status code

The API does not use 301 status code (permanent redirection) and 302 status code (temporary redirection, 307 also means this), because they can be returned by the application level, and the browser will jump directly. The API level can ignore these two situations.

The API mainly uses 303 See Other to refer to another URL. It has the same meaning as 302 and 307. It is also "temporary redirection". The difference is that 302 and 307 are used for GET requests, while 303 is used for POST, PUT and DELETE requests. After receiving 303, the browser will not automatically jump, but let the user decide what to do next. Here is an example.

HTTP/1.1 303 See Othe
Location: /api/orders/12345

4xx status code

4xx status code indicates client error, mainly including the following:

400 Bad Request: The server did not understand the client's request and did not do any processing.
401 Unauthorized: The user did not provide authentication credentials or failed authentication.
403 Forbidden: The user is authenticated but does not have the required permissions to access the resource.
404 Not Found: The requested resource does not exist or is not available.
405 Method Not Allowed: The user has been authenticated, but the HTTP Method is not within his authority.
410 Gone: The requested resource has been transferred from this address and is no longer available.
415 Unsupported Media Type: The return format requested by the client is not supported. For example, API Only return JSON Format, but the client requires it to return XML Format.
422 Unprocessable Entity : The attachment uploaded by the client cannot be processed, resulting in the failure of the request.
429 Too Many Requests: The number of requests from the client exceeds the limit.

5xx status code

5xx status code indicates server error. Generally speaking, the API will not disclose the details of the server to the user, so only two status codes are enough.

500 Internal Server Error: The client request is valid and an unexpected error occurred while the server was processing it.
503 Service Unavailable: The server cannot process the request, which is generally used to maintain the status of the website.

Data return

GET         Single object, collection
POST        Successfully added object
PUT/PATCH   Successfully updated object
DELETE      empty

5, Version

API domain names can be selected in two forms:

• Use exclusive domain name API example. com
• Master domain name + / API form, such as example com/api

Common methods of API version:

• Domain name + V1 / such as API example. com/v1
• Accept Header Accept: application/json+v1
• Custom Header: X-Api-Version: 1

reference resources: 
https://restfulapi.cn/
https://novoland.github.io / design / 2015/08/17/Restful%20API%20 design specification html