Principles of REST style

A good restful API should have the following features:

1. This API should be browser-friendly and can be well integrated into the web, rather than incompatible with the Web.

   Browsers are the most common and common rest clients. Good restful APIs should be able to use browsers + HTML to complete all tests (no programming language is required ). Such APIs can also be easily tested using various automated Web function testing and performance testing tools. Web Front-end applications (browser-based Ria applications, mobile apps, etc.) can also easily combine multiple restful API functions to build mashup applications.

2. The resources contained in this API and operations on resources should be intuitive and easy to understand, and comply with the requirements of the HTTP protocol.

   Rest development is also called "resource-oriented development", which indicates that resource abstraction is the core content of restful API design. The Restful API modeling process is similar to object-oriented modeling, and is based on nouns. These terms are resources. Any naming abstract concept can be defined as a resource. The HTTP protocol is not a Transport Agreement. It actually provides a unified interface for operating resources. Any operations on resources should be mapped to several limited HTTP methods (commonly used methods include get/post/Put/delete, there are also uncommon patch/head/options methods) above. Therefore, the restful API modeling process can be viewed as an object-oriented modeling process with unified interface constraints.

   According to the HTTP protocol, the get method is secure and idempotent. The post method is neither secure nor idempotent (it can be used as a wildcard method for all write operations ), put and delete methods are insecure but idempotent. Map operations on resources to these four methods reasonably, not using a specific method (for example, over-using the get or post methods ), so that the four methods of HTTP are not enough.

   If you find that there are too many operations on resources, so that the HTTP method is not enough, you should consider designing more resources. Designing more resources (and corresponding URIs) does not harm restful APIs.

3. This API should be loosely coupled.

   Restful APIs are designed in three steps: Resource abstraction, unified interface, and Hypertext-driven. These three layers ensure the loose coupling of restful APIs.

   When designing APIs for the Internet, loose coupling becomes a mandatory requirement. Tightly coupled APIs are very fragile. Once published, neither the server nor the client can continue to evolve. In particular, on the server side, the released interfaces cannot be changed. After the changes, almost all client applications cannot work immediately. The rest architecture style is the antidote to tightly coupled APIs. This topic can be discussed very deeply and will not be discussed here. For more information, see rest practices.

4. The expression format used in this API should be a common format.

   In restful APIs, resource operations are performed indirectly by transmitting resource expressions between the server-client. Resource expressions can be in many formats, and the resource expressions in the response and request formats are also different. The resource expression formats in get/post responses are commonly HTML, XML, and JSON. The resource expression formats in post/put requests are commonly standard HTML form parameters, XML, and JSON.

   These common expressions are easy to process and support a large number of frameworks and libraries. Therefore, unless reasonably required, you do not need to use a custom private format.

5. Use http response status code to express various error situations

   The HTTP response status code is a standard mechanism used to express errors in the unified HTTP interface. The response status code is divided into two parts: Status Code and reason phase. The two parts are customizable. You can also use standard status code to customize only the reason phase.

   If a so-called "Restful API" returns a 200 OK response to any request and an error message is returned in the Response Message Body, this obviously does not meet the basic requirements of the rest architecture style of "ensuring the visibility of operation semantics.

6. This API should be friendly to the HTTP Cache

   Making full use of HTTP cache is fundamental to restful API scalability. HTTP is a layered architecture. Many intermediate components can be inserted from the user agent at both ends to the origin server. Cache can be set in many locations throughout the HTTP Communication chain. The HTTP protocol has a good caching mechanism, which can be divided into two sets: The expiration model and the verification model. If the API designer has not considered how to use the HTTP cache, the scalability of this API will be subject to many problems.

Principles of REST style