Understanding RESTful architecture && RESTful API Design Guide

RESTful is the design idea used in both the front-end and back-end interfaces.

The website is the software, we also often say webapp, this kind of Internet software uses "the client/server" mode, builds on the distributed system. Web site development, can also fully adopt the model of software development , but the traditional software and networks are different areas, because: software development is mainly for the single-machine environment, and the network is the communication between the research system. The rise of the Internet has enabled these two areas to converge, and now we are beginning to consider how to develop software for use in the Internet environment.

• The restful architecture, which is currently the most popular Internet software architecture, is well-structured, standards-compliant, easy to understand and easy to expand, so it is being used by more and more websites.

RESTful architecture Author

The word rest is fielding proposed. He is the main designer of the HTTP protocol (1.0 and 1.1), one of the designers of the Apache Server Software, and the first president of the Apache Foundation.

Rest author Fielding this: rest is to understand and evaluate the architecture design of network-based application software in accordance with the principle of architecture, and get a powerful, powerful and suitable communication architecture .

RESTful name

Fielding his architecture principles for Internet software, named rest, the abbreviation for representational state Transfer (Presentation level transition). If an architecture conforms to the rest principle, it is said to be a restful architecture .

If we want to understand what the restful architecture is, we have to understand the word representational state Transfer , and only every word knows what it means to better understand how rest is designed.

　　

Resources

In the name of rest ' representation State transformation ', the subject is omitted , and the presentation layer actually refers to the expression layer of ' resources '.

The so-called " resources ", is an entity on the network, or is a specific information on the network. It can be a piece of text, a picture, a song, a service, in short, is a concrete reality . you can point to it with a URI (Uniform Resource Locator), and each resource corresponds to a specific URI. To get this resource, access its URI so that the URI becomes the address of each resource or a unique identifier .

The so-called "surfing the Internet" is to interact with a series of "resources" on the Internet and invoke its URI.

Presentation layer (representation)

A "resource" is an information entity that can have a variety of external representations. We take the form of "resources" specifically, called its "presentation Layer" (representation).

For example, text can be expressed in TXT format, can also be used in HTML format, XML format, JSON format, and even binary format can be used, images can be in JPG format, can also be used in PNG format.

The URI represents only the entity of the resource and does not represent its form. Strictly speaking, some URLs last ". html" suffix is unnecessary, because this suffix name represents the format, which belongs to the "presentation layer" category, and the URI should only represent the location of the "resource". Its specific representation should be specified in the header information of the HTTP request with the Accept and Content-type fields, which is the description of the "presentation layer".

State conversion (Transfer)

Accessing a Web site represents an interactive process between the client and the server. In this process, data and state changes are bound to be involved.

The Internet Communication Protocol HTTP protocol is a stateless protocol. This means that all States are saved on the server side. Therefore, if the client wants to operate the server, there must be some way to make the server side "state Transfer". And this transformation is based on the expression layer, so is the "Expression Layer state transformation."

The method that the client uses, can only be the HTTP protocol. Specifically, there are four verbs in the HTTP protocol that represent the mode of operation: GET, POST, PUT, DELETE. They correspond to four basic operations: get is used to get a resource, post is used to create a new resource (and can also be used to update resources), put is used to update resources, and delete is used to delete resources.

Review

Combining the above explanations, we summarize what a restful architecture is:

(1) each URI represents a resource ;

(2) between the client and the server, the transmission of such resources of some kind of performance layer ;

(3) The client through four HTTP verbs, the server-side resources to operate, to achieve "performance layer State transformation ."

RESTful Design Myths

The restful architecture has some typical design pitfalls.

One of the most common design errors is that the URI contains verbs. Because "resource" represents an entity, it should be a noun, the URI should not have verbs, the verb should be placed in the HTTP protocol.

For example, a URI is/POSTS/SHOW/1, where show is a verb, the URI is wrong, the correct wording should be/posts/1, and then the show is represented by a GET method.

Another design mistake is to include the version number in the URI.

http://Www.example.com/app/1.0/foo http://www.example.com/app/1.1/foo http: // Www.example.com/app/2.0/foo

Because different versions can be understood as different representations of the same resource, the same URI should be used. The version number can be distinguished in the Accept field of the HTTP request header information.

RESTful API

The Web application is divided into two parts, front end and back end. The current trend is the emergence of the front-end equipment (mobile phones, tablets, desktop computers, other special equipment ...) ）。

　　Therefore, there must be a unified mechanism to facilitate the communication of different front-end devices to the backend. This leads to the popularity of API architectures and even the idea of ' API first ' design. RESTful API is currently a more mature set of Internet Application API design.

Agreement

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

Domain name

The API should be deployed under a dedicated domain name whenever possible.

HTTPS://api.example.com

We can often see a similar API as the beginning of the domain name.

If the API is simple, we can put it under the main domain name:

HTTPS://example.org/api/

For example, the most common one is the Turing's API interface:

http://WWW.TULING123.COM/OPENAPI/API?KEY=20FF1803FF65429B809A310653C9DAAC

Version

The version number of the API should be said to be placed in the URL.

HTTPS://api.example.com/v1/

　　

Another option is to put the version number in the HTTP header information, but it is not as easy to put in the URL as intuitive. GitHub uses this approach.

Path

The path is also called the ' End Point ', 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/zoos
• Https://api.example.com/v1/animals
• Https://api.example.com/v1/employees

HTTP verbs

For the specific operation type of the resource, it is represented by an HTTP verb.

The usual HTTP verbs have the following five (the corresponding SQL command in parentheses).

GET (SELECT): Remove resources from the server (one or more items). POST (Create): Creates a new resource on the server. PUT (UPDATE): Updates the resource on the server (the client provides a full resource after the change). PATCH (UPDATE): Updates the resource on the server (the client provides changed properties). Delete: Deletes a resource from the server.

There are also two infrequently used HTTP verbs.

　　

• HEAD: Gets the metadata for the resource.
• OPTIONS: Gets information about which properties of a resource are available to the client to change.

Here are some examples.

GET///zoos//zoos//zoos//zoos//zoos/id//zoos/id/ ANIMALS/ID: Delete a designated animal from a designated zoo

　　

Filter information

If the number of records is large, the server will not be able to return them to the user. The API should provide parameters to filter the returned results.

The following are some common parameters.

limit=: Specify the number of records to return ? offset=: Specifies the start position of the returned record. page=2&per_page=: Specify the number of pages, and how many records per page. ? sortby=name&order=ASC: Specifies which property the returned results are sorted by, and the sort order. animal_type_id=1: Specify filter criteria

In fact, these are the parameters we pass in the GET request, including the limit bar number, the offset limit start position and so on are some of our common request parameters for filtering.

Status code

The status code and prompt information returned by the server to the user is usually the following (the HTTP verb corresponding to the status code in square brackets). that is, the status code is the background according to the situation written to the front end, 400, 200, 404 and so on. status codes still need to be written correctly, so that the front-end is accurate to determine whether the problem is the front-end or back-end.

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

Error handling

If the status code is 4xx, you should return an error message to the user. In general, error is used as the key name in the returned information, and error information is used as the key value. As follows:

{    error: "Invalid API key"}

　

return results

For different operations, the results returned by the server to the user conform to the following specification.

GET//collection///collection//collection//collection/ Resource: Returns an empty document

Hypermedia API

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

For example, when a user makes a request to the root directory of api.example.com, a document is obtained.

　　

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

The code above indicates that there is a link property in the document, and the user reads this property and knows what API to call next. Rel represents the relationship between this API and the current URL (collection relationship, and gives the collection URL), the href represents the path to the API, title represents the API's caption, and type represents the return type.

The design of the Hypermedia API is known as Hateoas. The GitHub API is the design that accesses api.github.com to get a list of URLs for all available APIs.

{  "current_user_url": "https://api.github.com/user", "authorizations_url": "https://api.github.com/authorizations",  // ...}

As you can see from the above, if you want to get information about the current user, you should go to the api.github.com/user and get the results below.

{  "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3"}

The above code indicates that the server gives the prompt information and the URL of the document.

https://api.github.com/

　　

　　

Understanding RESTful architecture && RESTful API Design Guide