In the tide of the mobile Internet, with the rise of technologies such as docker, the concept of “microservices” is more and more accepted and applied in practice, the increasing number of web services gradually unified in the RESTful architecture style, if the developer does not understand the RESTful architectural style, the development of the so-called RESTful API will always be out of sync, not enough! If developers do not know much about RESTful architecture style, the so-called RESTful APIs they develop will always look different and not standardized enough.

This article is some of my understanding of the RESTful architectural style, and I’d like to share it with you, so feel free to discuss if you have any questions.

 1. RESTful architecture style

The RESTful architecture style was originally proposed by Roy T. Fielding (head of the HTTP/1.1 protocol expert group) in his 2000 Ph.D. dissertation, and HTTP is a typical application of this architecture style. Since its inception, HTTP has been increasingly favored by architects and developers for its scalability and simplicity. On the one hand, with the rise of cloud computing and mobile computing, many enterprises are willing to share their data and functions on the Internet; on the other hand, RESTful APIs (also known as RESTful Web services) have gradually surpassed SOAP as one of the most important means of realizing SOA in enterprises. To this day, the RESTful architecture style has become the standard for enterprise-level services.

REST is the acronym of Representational State Transfer, which can be translated as “Representation Layer State Transformation”. several of the biggest features of REST are: resources, unified interface, URIs and statelessness.

 1.1 Characteristics of the RESTful architecture style

 1.1.1 Resources

A “resource” is an entity on the Web, or a specific piece of information on the Web. It can be a paragraph of text, a picture, a song, a service, in short, a specific real. Resource always through some kind of carrier to respond to its content, the text can be expressed in txt format, can also be expressed in HTML format, XML format, or even binary format; pictures can be expressed in JPG format, can also be expressed in PNG format; JSON is now the most commonly used format for resource representation.

 Combined with my development practices, I understand resources and data as follows:

A resource is a user-oriented set of datasets in json (or other Representation), and a resource’s representation of information tends to favor the data in the conceptual model:

  • Resources are always displayed in some kind of Representation, i.e. serialized information

  • Commonly used Representation is json (recommended) or xml (not recommended), etc.

  • Represntation is the presentation layer of the REST architecture.

In contrast, data (especially databases) are a more abstract, computer-efficient and computer-friendly representation of data, existing more in logical models

 The resource and data relationships are shown below:

 1.1.2 Harmonization of interfaces

RESTful architecture style provides that the meta-operations of data, i.e., CRUD (create, read, update and delete, i.e., add, delete, check and change data) operations, correspond to HTTP methods: GET for getting resources, POST for creating new resources (which can be used for updating resources), PUT for updating resources and DELETE for deleting resources. resources, so that a unified interface for data operations, only through the HTTP method, you can complete all the data additions, deletions, checks and changes.


  • GET (SELECT): take out resources (one or more) from the server.

  • POST (CREATE): creates a new resource at the server.

  • PUT (UPDATE): update the resource at the server (the client provides the full resource data).

  • PATCH (UPDATE): update the resource at the server (the client provides the resource data to be modified).

  • DELETE (DELETE): Delete the resource from the server.

 1.1.3 URIs

A resource can be pointed to with a URI (Uniform Resource Locator), i.e. each URI corresponds to a specific resource. To get to this resource, access its URI, so the URI becomes the address or identifier of each resource.

In general, each resource has at least one URI that corresponds to it, the most typical URI being the URL.

 1.1.4 Statelessness

The so-called stateless, that is, all the resources, can be located by URI, and this location is not related to other resources, and will not be changed because of changes in other resources. The difference between stateful and stateless, take a simple example to illustrate. Such as querying the salary of an employee, if the query is required to log in to the system, enter the page of the query salary, perform the relevant operations, get the amount of salary, then this case is  , because each step of the query salary operation depends on the previous operation, as long as the previous operation is unsuccessful, the subsequent operation can not be executed; if you enter a url to get the salary of the specified employee, then this case is  because Getting the salary does not depend on any other resource or state, and in this case, the employee’s salary is a resource, which is corresponded to by an url, and the resource can be obtained through the GET method in HTTP, which is a typical RESTful style.

 1.2 ROA, SOA, REST and RPC

ROA That is, Resource Oriented Architecture, RESTful architecture style services are centered around  , is a typical ROA architecture (although the “A” and “architecture” there is a duplication, but say no harm), the ROA and SOA are not conflicting, or even see ROA as a kind of SOA. Although ROA and SOA are not in conflict, and it is not wrong to consider ROA as a kind of SOA, since RPC is also SOA, and a few older papers, blogs, or books often discuss SOA and RPC together, RESTful architecture style services are usually referred to as ROA architectures, and SOA architectures are seldom mentioned in order to distinguish them from RPC in a more explicit way. RPC.

RPC style used to be the mainstream of Web Services, initially based on the XML-RPC protocol (a remote procedure call (RPC) distributed computing protocol), and later gradually replaced by SOAP protocol (Simple Object Access Protocol)) RPC style services, not only can use HTTP , but also can use TCP or other communication protocols. However, RPC-style services, by the development of services using the language constraints are relatively large, such as the .NET framework, the development of web service is the traditional way to use WCF, based on the WCF development services, that is, RPC-style services, the use of the client side of the service is usually to be realized in C#, if the use of python or other languages, it is difficult to realize that can be directly communicated with the client side of the service. After entering the mobile Internet era, RPC style services are difficult to use in mobile terminals, while RESTful style services, due to the fact that you can directly use json or xml as a carrier to carry data, HTTP method as a unified interface to complete the data operation, the client development does not depend on the technology of the service implementation, mobile terminals can also be easy to use the service, which also exacerbated REST to replace the RPC to become the dominant web service’s dominance.

 The difference between RPC and RESTful is shown in the following two diagrams:

 1.3 True REST and hybrid style

Usually developers do service-related client development, the use of the so-called RESTful services, basically can be divided into  REST and hybrid  two categories.  REST That is, the RESTful architectural style I described above, with the above four characteristics, is the real sense of RESTful style; and hybrid风格 , just borrowed some of the advantages of RESTful, with some of the characteristics of RESTful, but still claim to be RESTful style services. (In my opinion, it is precisely because hybrid style services confuse the concept of RESTful that the concept of true REST is put forward in the RESTful architectural style, in order to divide the boundary :P)

The most mainstream use of hybrid style is to use GET method to get resources, and use POST method to create, modify and delete resources. The reason why hybrid style exists, according to me, there are two sources: one is because some developers don’t really understand what is the RESTful architectural style, resulting in the development of the service seems to be different from the other; and the mainstream reason is because of the historical baggage — The service was originally RPC style, due to the disadvantages of RPC and the advantages of RESTful mentioned above, the developer wrapped another layer of RESTful shell on the RPC style service, usually this layer of shell is only for the service of obtaining resources, so it will be implemented according to the RESTful style of the GET method, if the If the client puts forward some simple requirements for creating, modifying or deleting data, the most commonly used POST method in the HTTP protocol is used to realize the corresponding function.

Therefore, developing RESTful services without historical baggage is not recommended to use hybrid style.

 2. Accreditation mechanisms

Since RESTful style services are stateless, the authentication mechanism is especially important. For example, the employee’s salary mentioned above, which should be a private resource that only the employee himself or a few other people with permissions are qualified to see. If you don’t make a layer of restriction on the resource through the permissions authentication mechanism, then all the resources are exposed in a public way, which is unreasonable and dangerous.

Authentication mechanisms address the problem of determining who the user is who is accessing a resource; permission mechanisms address the problem of determining whether the user is licensed to use, modify, delete, or create the resource. Permission mechanisms are usually tied to the business logic of the service, so permission mechanisms need to be customized within each system, while authentication mechanisms are essentially generic, and commonly used authentication mechanisms include session auth (i.e., logging in with a username and password), basic auth , token auth , and OAuth , with the latter three commonly used authentication mechanisms in service development.

2.1 Basic Auth

HTTP Basic authentication (BA) implementation is the simplest technique for enforcing access controls to web resources because it doesn’t require cookies, session identifier and login pages. Rather, HTTP Basic authentication uses static, standard fields in the HTTP header which means that no handshakes have to be done in anticipation.

In short, Basic Auth is the simplest authentication method used with RESTful APIs, which only requires a username and password, but is used less and less in production environments due to the risk of exposing the username and password to third-party clients. Therefore, when developing RESTful APIs that are open to the public, try to avoid using Basic Auth.

2.2 Token Auth

Token Auth is not commonly used , it is different from Basic Auth is not the user name and password sent to the server for user authentication , but to the server to send a pre-generated server-side token to do the authentication . Therefore, Token Auth requires the server to have a complete set of Token creation and management mechanism, the implementation of the mechanism will increase a large number of non-essential server-side development work, but also do not see this mechanism is safe enough and universal, so Token Auth is not used much.

This article does not expand on the introduction of Token Auth, my personal understanding of this mechanism is limited, interested in understanding the mechanism of the students may be interested in this discussion on Stack Overflow to start.

2.3 OAuth

OAuth is an open standard for authorization. OAuth provides client applications a ‘secure delegated access’ to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials. Designed specifically to work with Hypertext Transfer Protocol (HTTP), OAuth essentially allows access tokens to be issued to third-party clients by an authorization server, with the approval of the resource owner. The client then uses the access token to access the protected resources hosted by the resource server. OAuth is commonly used as a way for Internet users to log into third party websites using their Microsoft, Google, Facebook or Twitter accounts without exposing their password.

OAuth is a service that is complementary to and distinct from OpenID. OAuth is also distinct from OATH, which is a reference architecture for authentication, not a standard for authorization. However, OAuth is directly related to OpenID Connect (OIDC) since OIDC is an authentication layer built on top of OAuth 2.0.

OAuth (Open Authorization) is an open authorization standard that allows a user to give a third-party application access to resources (e.g., photos, videos, contact lists) that the user has stored privately on a particular web service without having to provide the username and password to the third-party application.

Instead of a username and password, OAuth allows users to provide a token to access their data stored with a specific service provider. Each token authorizes a specific third-party system (e.g., a video editing site) to access a specific resource (e.g., just the videos in a particular album) for a specific period of time (e.g., within the next 2 hours). In this way, OAuth lets users authorize third-party sites to access some specific information they have stored with another service provider, but not all content.

It is because of the rigor and security of OAUTH that OAUTH has now become the most commonly used authentication mechanism in the RESTful architectural style and, together with the RESTful architectural style, has become the standard for enterprise-class services.

OAuth has been developed from OAuth1.0 to OAuth2.0, but the two are not a smooth transition upgrade, OAuth2.0 under the premise of ensuring security greatly reduces the complexity of the client’s development, therefore, Gevin suggests that in the real-world applications using OAuth2.0 authentication mechanism.

Now on the Internet about OAuth information is very rich, there are a large number of open source third-party libraries to implement the OAuth mechanism, students who are not familiar with OAuth from the OAuth official website to start.

 3. Summary

  • True REST + OAuth is RESTful is the standard for microservices
  •  Basic Auth is only used in development environments
  •  Well-designed resources
  •  Send the correct request for the data using the correct HTTP method

 Extended reading: RESTful API writing guide

By lzz

Leave a Reply

Your email address will not be published. Required fields are marked *