RESTful API Design Overview

First, Introduction

1. What is rest

Rest full name is representational state Transfer, Chinese meaning is the expression (Editor's note: usually translated as a representation) of the transfer of sexual status. It first appeared in the 2000 Roy fielding doctoral dissertation, and Roy Fielding was one of the main authors of the HTTP specification. In his paper, he mentions: "The purpose of my writing is to understand and evaluate the architecture design of network-based application software in accordance with the principle of architecture, and to obtain a structure with strong function, good performance and suitable communication." Rest refers to a set of schema constraints and principles. "If an architecture conforms to rest's constraints and principles, we call it a restful architecture."

Rest itself does not create new technologies, components, or services, and the idea behind restful is to use the existing features and capabilities of the web to better use some of the guidelines and constraints in existing Web standards. While rest itself is deeply affected by web technology, the rest architecture style is theoretically not bound to HTTP, except that HTTP is currently the only instance of rest. So the rest we describe here is also the rest that is implemented via HTTP.

Characteristics:

• Rest is not technology-related, it represents a software architecture style, rest is the abbreviation for representational state transfer, and Chinese translates as "representational states transfer"
• Rest looks at the entire network from the resource's perspective, which identifies the resources distributed across a node in the network through URLs, and the client application uses URLs to obtain representations of the resources, resulting in these applications transforming state
• Rest is not technology-related, it represents a software architecture style, rest is the abbreviation for representational state transfer, and Chinese translates as "representational states transfer"
• All the data, but the data obtained through the network or operation (increase and deletion), are resources, all the data as a resource is the most essential attribute of rest difference and other architectural style
• For the resource-oriented architectural style of rest, a new architectural concept is proposed, namely: resource-oriented architecture (Roa:resource oriented Architecture)

Second, RESTful API design

1. Agreement

• The API communicates with the user protocol, always using the HTTPS protocol.

2. Domain Name

• Https://api.example.com try to deploy the API to a dedicated domain name (there are cross-domain issues)
• Https://example.org/api/API is simple.

3. Version

• URLs, such as: https://api.example.com/v1/version numbers to URLs, such as K8s's Apiserver
• Raises multiple requests when a version is placed across a domain in the request header

4. Path

The path is also called the "End point" (endpoint), which represents the specific URL of the API.

In a restful architecture, each URL represents a resource (resource), so there can be no verbs in the URL, only nouns, and nouns often correspond to the table names in the database. In general, the tables in the database are "collections" (collection) of the same record, so nouns in the API should also use complex numbers. For example, there is an API that provides information about zoos, as well as information about various animals and employees, and its path should be designed as follows.

https://api.example.com/v1/Zooshttps://api.example.com/v1/Animalshttps://api.example.com/v1/employees

5.http method

GET (SELECT): Remove resources (one or more items) from the server, secure and idempotent. POST (Create): Create a new resource on the server, unsafe, and not idempotent put (update): Updates the resource on the server (the client provides a changed full resource), unsecured but idempotent patch (UPDATE): Updates the resource on the server (the client provides the changed properties). Delete: Removes resources from the server, insecure but idempotent head: Gets the metadata for the resource. OPTIONS: Gets information about which properties of a resource are available to the client to change.  ## # #使用列子GET///zoos//zoos//zoos//zoos/  /zoos/id//zoos/id/animals/id: Delete a designated animal from a designated zoo

6. Filter, pass the search condition in the form of URL upload parameter

• HTTPS://API.EXAMPLE.COM/V1/ZOOS?LIMIT=10: Specifies the number of records returned
• HTTPS://API.EXAMPLE.COM/V1/ZOOS?OFFSET=10: Specifies the start position of the returned record
• HTTPS://API.EXAMPLE.COM/V1/ZOOS?PAGE=2&PER_PAGE=100: Specify pages, and the number of records per page
• HTTPS://API.EXAMPLE.COM/V1/ZOOS?SORTBY=NAME&ORDER=ASC: Specifies which attribute the returned result is sorted by, and the sort order
• Https://api.example.com/v1/zoos?animal_type_id=1: Specifying filter criteria

7. Status Code usage

$ OK-[GET]: The server successfully returned the data requested by the user, the operation is idempotent (idempotent). 201 CREATED-[post/put/PATCH]: User new or modified data succeeded. 202 Accepted-[*]: Indicates that a request has entered the background queue (asynchronous task)204 NO CONTENT-[Delete]: The user deleted the data successfully. INVALID REQUEST-[post/put/PATCH]: The user made a request error, the server did not create new or modify the data operation, the operation is idempotent. 401 Unauthorized-[*]: Indicates that the user does not have permissions (token, user name, password error). 403 Forbidden-[*] Indicates that the user is authorized (relative to the 401 error), but access is forbidden. 404 Not FOUND-[*]: The user made a request for a nonexistent record, the server did not operate, the operation is idempotent. 406 Not acceptable-[GET]: User requested format is not available (such as user request JSON format, but only XML format). 410 Gone-[get]: The resource requested by the user is permanently deleted and will no longer be available. 422 unprocesable Entity-[post/put/PATCH] A validation error occurs when an object is created. $ INTERNAL Server Error-[*]: The server is having errors and the user will not be able to determine if the request was successful.

8. Error handling

Error handling, the status code is 4xx, you should return an error message, error as key.

9. Return results

• Get/collection: Returns a list of resource objects (arrays)
• Get/collection/resource: Returns a single Resource object
• Post/collection: Returns the newly generated resource object
• Put/collection/resource: Returns the full resource object
• Patch/collection/resource: Returns the full resource object
• Delete/collection/resource: Returns an empty document

10. Hyperlink API

The RESTful API is best done with hypermedia, which provides links to the returned results, and even to other API methods, so that users do not look up documents and know what to do next

{"Link": {  "rel":"Collection Https://www.example.com/zoos",  "href":"Https://api.example.com/zoos",  "title":"List of Zoos",  "type":"Application/vnd.yourformat+json"}}

11. Other

(1) The identity 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 to avoid using XML.

Reference: 1.https://www.cnblogs.com/wupeiqi/articles/7805382.html

2.51011425

3.http://www.ruanyifeng.com/blog/2014/05/restful_api.html

RESTful API Design Overview