| 1. Introduction |
1. What is REST
The full name of REST is Representational State Transfer, which in Chinese means representational (Editor's Note: usually translated as representational) state transfer. It first appeared in 2000 in the doctoral dissertation of Roy Fielding, one of the main writers of the HTTP specification. He mentioned in the paper: "The purpose of my writing this article is to understand and evaluate the architecture design of network-based application software under the premise of conforming to the principles of architecture, so as to obtain a strong function, good performance, suitable for communication. An architecture. REST refers to a set of architectural constraints and principles." If an architecture conforms to the constraints and principles of REST, we call it a RESTful architecture.
REST itself does not create new technologies, components or services, but the idea behind RESTful is to use the existing features and capabilities of the Web and better use some of the guidelines and constraints in existing Web standards. Although REST itself is deeply influenced by Web technology, in theory, the REST architectural style is not bound to HTTP, but currently HTTP is the only instance related to REST. So the REST we describe here is also REST over HTTP.
Features:
- REST has nothing to do with technology, and represents a software architecture style. REST is the abbreviation of Representational State Transfer, which translates to "representational state transfer" in Chinese.
- REST looks at the entire network from the perspective of resources. It identifies resources distributed on a node in the network through URLs. Client applications obtain resource representations through URLs, and obtaining these representations causes these applications to change states.
- REST has nothing to do with technology, and represents a software architecture style. REST is the abbreviation of Representational State Transfer, which translates to "representational state transfer" in Chinese.
- All data, whether it is acquired through the network or manipulated (add, delete, modify and check), are resources. Treating all data as resources is the most essential attribute that distinguishes REST from other architectural styles.
- For the resource-oriented architecture style of REST, some people propose a new structural concept, namely: Resource Oriented Architecture (ROA: Resource Oriented Architecture)
| 2. RESTful API design |
1. Agreement
- The communication protocol between the API and the user always uses the HTTPs protocol .
2. Domain name
- https://api.example.com try to deploy the API on a dedicated domain name (there will be cross-domain problems)
- https://example.org/api/ API is simple
3. Version
- URL, such as: https://api.example.com/v1/ The version number is placed in the url, such as the apiserver of k8s
- Put the version in the request header When cross-domain, it will cause multiple requests to be sent
4. Path
The path, also known as the "endpoint", represents the specific URL of the API.
In the RESTful architecture, each URL represents a resource (resource), so there can be no verbs in the URL, only nouns, and the nouns used often correspond to the table names in the database. In general, tables in a 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 information about a zoo, and also includes information about various animals and employees, its path should be designed as follows.
https://api.example.com/v1/zoos https://api.example.com/v1/animals https://api.example.com/v1/employees
5. http method
GET (SELECT): Retrieve resource(s) from the server, safe and idempotent. POST (CREATE): Create a new resource on the server, insecure and not idempotent PUT (UPDATE): Update the resource on the server (the client provides the complete resource after the change), insecure but idempotent PATCH (UPDATE): Update the resource on the server (client provides changed properties). DELETE (DELETE): deletes a resource from the server, unsafe but idempotent HEAD: Get metadata of the resource. OPTIONS: Get information about which properties of the resource can be changed by the client. # ### Use column GET / zoos: list all zoos POST / zoos: create a new zoo GET /zoos/ ID: Get information about a specified zoo PUT /zoos/ ID: Update the information of a specified zoo (provide all the information of the zoo) PATCH /zoos/ ID: Update the information of a specified zoo (provide some information about the zoo) DELETE /zoos/ ID: delete a zoo GET /zoos/ID/ animals: List all animals in a given zoo DELETE /zoos/ID/animals/ID: delete a specified animal in a specified zoo
6. Filter, pass the search criteria in the form of uploading parameters in the url
- https://api.example.com/v1/zoos?limit=10: Specifies the number of returned records
- https://api.example.com/v1/zoos?offset=10: Specifies the start position of the returned records
- https://api.example.com/v1/zoos?page=2&per_page=100: Specify the number of pages and the number of records per page
- https://api.example.com/v1/zoos?sortby=name&order=asc: Specify which property to sort the returned results by and the sort order
- https://api.example.com/v1/zoos?animal_type_id=1: Specify filter criteria
7. Status code usage
200 OK - [GET]: The server successfully returned the data requested by the user, the operation is idempotent (Idempotent). 201 CREATED - [POST/PUT/ PATCH]: User created or modified data successfully. 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, and the server does not create or modify data. This operation is idempotent. 401 Unauthorized - [* ]: Indicates that the user has no authority (token, username, password incorrect). 403 Forbidden - [* ] indicates that the user is authorized (as opposed to a 401 error), but access is forbidden. 404 NOT FOUND - [* ]: The request issued by the user is for a record that does not exist, and the server did not perform the operation, which is idempotent. 406 Not Acceptable - [GET]: The format requested by the user is not available (for example, the user requested JSON format, but only XML format). 410 Gone - [GET]: The resource requested by the user has been permanently deleted and will not be available again. 422 Unprocesable entity - [POST/PUT/ PATCH] A validation error occurred while creating an object. 500 INTERNAL SERVER ERROR - [*]: An error occurred on the server, and the user will not be able to determine whether the request made was successful.
8. Error handling
Error handling, when the status code is 4xx, an error message should be returned, and error is used as the key.
9. Return the result
- GET /collection: Returns a list (array) of resource objects
- GET /collection/resource: returns a single resource object
- POST /collection: returns the newly generated resource object
- PUT /collection/resource: returns the complete resource object
- PATCH /collection/resource: returns the complete resource object
- DELETE /collection/resource: returns an empty document
10. Hyperlink API
The RESTful API is best to be Hypermedia, that is, to provide links in the returned results to connect to other API methods, so that users can know what to do next without checking documents
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
11. Others
(1) The authentication of the API should use the OAuth 2.0 framework.
(2) The data format returned by the server should use JSON as much as possible and avoid using XML.
参考 ： 1.https: //www.cnblogs.com/wupeiqi/articles/7805382.html
2.https://blog.csdn.net/tjgamejx2/article/details/51011425
3.http://www.ruanyifeng.com/blog/2014/05/restful_api.html