How to design restful API features that are good for restful APIs

Original address: http://blog.csdn.net/ywk253100/article/details/25654021

Guide: Designing restful APIs is critical to the scalability, scalability, and consumer experience of software architectures. The theme of this virtual workshop is how to design restful APIs.

Keywords: restful API REST OAuth protocol

The REST architectural style was originally proposed by Roy T. Fielding (head of the http/1.1 Protocol Expert Group) in his 2000 doctoral dissertation. HTTP is a typical application of this architectural style. Since its inception, it has been favored by a growing number of architects and developers for its extensibility and simplicity. It is bound to be more developed. On the one hand, with the rise of cloud computing and mobile computing, many enterprises are willing to share their data, functions on the Internet, on the other hand, in the enterprise, RESTful API (also known as RESTful Web services) has gradually surpassed soap as an important means to realize SOA. To this end, Infoq will delve deeper into rest, readers through a series of in-depth articles and virtual discussions.

Designing RESTful APIs is critical to the scalability, scalability, and consumer experience of software architectures. The theme of this virtual workshop is how to design restful APIs. We have invited a few experts in the rest-style architecture and restful API design, and asked them to talk about their own practical experience on this issue. They were Li Yu, Li Jianye, Jonathan Allen, Majun.

Problem

The questions we designed for this virtual workshop are:

1. What is a good restful API? Believe that everyone has their own standards of judgment. So, what do you think a good restful API should have?
2. Security is a constant topic, for WSDL-and SOAP-based Web Service, we have ws-security security specifications to guide the implementation of authentication, authorization, identity management and other security requirements. So, is there any mature specification or implementation framework for RESTful APIs? How to ensure the security of RESTful API?
3. How do I version control the RESTful API, share what you think is practical?
4. Does the verb given in the HTTP1.1 specification suffice for designing restful APIs? Do you expand your verbs in the actual project? Under what circumstances do I need to expand?
5. Which is the most valuable feature of the JAX-RS 2.0 specification released this May for the design of RSTFULAPI? What problems does it (are) used to solve?
6. Can you recommend a useful RESTful API development framework for INFOQ readers and explain why you are promoting them?
7. What is your expectation of the HTTP2.0 specification being developed?

InfoQ: What is a good restful API? Believe that everyone has their own standards of judgment. So, what do you think a good restful API should have?

Li Yu: A good restful API should have the following characteristics: The API should be browser-friendly and fit nicely into the web, rather than being incompatible with the web. 1. The browser is the most common and most common rest client. A good restful API should be able to use the browser +html to complete all the tests (no programming language is required). Such APIs can also be easily tested using a variety of automated web functional testing and performance testing tools. Web front-end applications (browser-based Ria apps, mobile apps, and so on) also make it easy to combine the functionality of multiple restful APIs to build mashup class applications. The resources contained in this API and the operations on the resources should be intuitive and easy to understand, and conform to the requirements of the HTTP protocol. Rest development is also referred to as "resource-oriented development", which shows that abstraction of resources is the core of designing restful APIs. The process of modeling RESTful APIs is similar to object-oriented modeling, which is centered on nouns. These nouns are resources, and any abstract concept that can be named is defined as a resource. The HTTP protocol is not a transport protocol, it actually provides a unified interface for operating resources. For any operation of the resource, it should be mapped to several limited methods of HTTP (commonly used with get/post/put/delete four methods, and the infrequently used Patch/head/options method) above. Therefore, the process of modeling RESTful API can be regarded as an object-oriented modeling process with uniform interface constraints. According to the provisions of the HTTP protocol, the GET method is safe and idempotent, the Post method is neither safe nor idempotent (can be used as all the write operation of the pass formula), PUT, delete methods are unsafe but idempotent. It is reasonable to map the operation of the resource to these four methods, neither excessive use of a method (such as overuse of the Get method or Post method), or adding too many operations so that the four methods of HTTP are not enough. 2. If you find that there are too many operations on the resource so that the HTTP method is not enough, you should consider designing more resources. Designing more resources (and the corresponding URIs) is harmless for restful APIs. This API should be loosely coupled. The RESTful API is designed to include three progressive, low-to-high levels: Resource abstraction, unified interface, and hyper-text driven. It is these three levels that ensure the loose coupling of restful APIs. 3. When designing an Internet-facing API, loose coupling becomes a "must have" strong demand. Tightly coupled APIs are fragile, and once published, neither the server nor the client can evolve continuously. In particular, the server-side, the published interface is not afraid to change, after the change, almost all client applications immediately do not work properly. Rest this architectural style is tightly coupled API antidote, this topic can be discussed very deep, this is not unfolded. Interested readers can refer to "rest combat". The presentation format used in this API should be a common universal format In the RESTful API, the operation of the resource is done indirectly through the representation of the resource passing between the server-side-client. Resources can be expressed in a number of formats, and resource representations in response and requests may be formatted differently. The format of resource representation in the Get/post response, common in HTML, XML, json;post/put requests in the resource presentation format, common with standard HTML form parameters, XML, JSON. 4. These common presentation formats are very easy to handle and have a large number of frameworks and libraries to support. Therefore, unless there is a reasonable requirement, the custom private format is usually not required. Use HTTP response status codes to express various error situations The HTTP response status code is the standard mechanism used by the HTTP protocol to express error conditions in this unified interface. The response status codes are divided into two parts: status code and Reason phase. Both parts are customizable, or you can use the standard status code to customize only the reason phase. 5. If a so-called "RESTful API" returns a $ OK response for any request, an error message is returned in the body of the response, which clearly does not conform to the basic requirements of the rest architectural style of "ensuring operational semantic visibility". This API should be friendly to the HTTP cache 6. Making the best use of HTTP caching is fundamental to restful API scalability. The HTTP protocol is a layered architecture that can insert many intermediate components from the user agent on both ends to Origin server. In many locations throughout the HTTP communication chain, the cache can be set. There is a good caching mechanism in the HTTP protocol, which can be divided into two sets of caching mechanisms: outdated model and validating model. If the API designer has not considered how to take advantage of HTTP caching at all, there are many problems with the scalability of this API.

Li Jianye: First of all, for the concept of rest, I generally understand it as a restful architecture, but now in practice the most widely recognized is HTTP, and it is an implementation of rest, so RESTFUL API can also be less strict referring to HTTP-based api--of course, even when it is not strict, The API itself should also strive to follow the rest architecture style. I think that the most important point of a restful api should be--"as little priori information as possible," which is also a criterion for me to judge a good restful api. such as HTTP verbs, in practice, you may often struggle with effective use of  HTTP  verbs, but this is not particularly important-unless you understand the value of doing so. The most important thing about the http  verb is that it is the act that the standard clarifies, that is, if our "client" follows the convention, then there is no need to invent a new verb, and there is no need to add a "priori information", but the so-called "priori Information" is directed at the client--to the API is the caller, For some enterprise internal system, or some traditional system, because "resource" is very stable, the operation of resources is also very stable, these systems "calling client" is not a browser but another system, if the force corresponds to the HTTP verb, it will become an additional "prior information", At this point I will not be too wedded to the HTTP verb, I have to make a set of verbs in the parameters can also be accepted-as long as the verb does not change, the system is still a restful style. Again, such as the response inside the Content-type, this is sometimes ignored by the novice, but this is very important, because generally involves the collaboration between the system API, often do not use ordinary text, it is more common to use JSON to express complex structure, This is different from the usual default understanding (the default is generally considered Text/plain and text/html), so if you forget to use Content-type for differentiation in the API, subsequent support for multiple types of client access becomes a trap (we have encountered this problem many times). This difficulty can be avoided if, at first, it is checked for additional prior knowledge (the default content-type is plain or allows the designation of Content-type).

Jonathan Allen: first, the uniform interface of HTTP should be used correctly, such as the verb of HTTP, if the exclusively post is indiscriminate, there is obviously room for improvement; Secondly, the resources have the appropriate granularity, can judge the granularity of the resources from three aspects is reasonable--the efficiency of the network, the size of the expression and the ease of use of the client; Finally, the presentation of the design, in addition to the body content of the expression, as well as the URI and links, these are the criteria for judging a RESTful API good or bad.

Majun: In my opinion, a good API standard is to use the HTTP protocol as much as possible, using HTTP as a transfer protocol rather than as a transport protocol. Includes, but is not limited to: use of HTTP verbs to clear the operation, including content negotiation, you can choose a resource based on the parameters provided by the request of the most appropriate media type, language, character set and encoding performance; different return codes are used to describe the various states. But many have actually seen that the RESTful APIs, both domestic and foreign, are not so much to meet these conditions. The API provided by Parse.com is a good restful API that I've seen, and can be used as a reference for example.

How to design restful API features that are good for restful APIs