What is a truly RESTful architecture?

For more information, see a little book I’ve been working on recently, The Microservice Best Practices Road, which is a pothole manual for projects.

What?

Representational State Transfer (REST) is a software architecture style developed by Dr. Roy Fielding in his doctoral thesis in 2000.

Roy Fielding was the principal designer of the HTTP protocol (versions 1.0 and 1.1), and in fact the HTTP 1.1 specification was designed based on the guiding principles of the REST architectural style. It is important to note that REST is a design style, not a standard, and if an architecture conforms to REST principles, we call it a RESTful architecture.

According to?

Back in ancient times the front end and back end were fused together, as was PHP, JSP, ASP, etc. (see my previous presentation on the Evolution of the Web Front End Development Model). In recent years, with the rapid development of mobile Internet, various types of clients emerge one after another. Therefore, a unified interface is required to provide services for Web, iOS, Android and even desktop. In addition, for the majority of platforms, such as Facebook Platform, Weibo open platform, wechat public platform, they do not need an explicit front end, only need a set of service interface, so RESTful is their best choice.

The best way to understand a RESTful architecture is to understand the phrase Representational State Transfer, which literally translates to “presentation layer State transformation,” but omits the subject. In fact, “presentation layer” refers to the “presentation layer” of “resources”, so generally speaking, resources transfer state in a certain form in the network. Break it down:

• Resource: data. Newsfeed, Friends, Order, etc.
• Representational: Some form of representation, such as JSON, XML, JPEG, etc.
• State Transfer: State change. Through HTTP verbs.

Then let’s look at a specific RESTful Architecture — Resource-Oriented Architecture (ROA) :

• Resources are specified by URIs. The so-called “surfing the Internet” is to interact with a series of “resources” on the Internet and call its URI.
• Operations on resources include obtaining, creating, modifying, and deleting resources, which correspond to the GET, POST, PUT, and DELETE methods provided by the HTTP protocol.
• Manipulate a resource by manipulating its representation. This should be specified in the Accept and Content-Type fields in the HTTP request header.
• Resources are represented as XML or HTML, depending on whether the reader is a machine or a human, a client software consuming a Web service or a Web browser. It can also be any other format.

How?

Applied to Web services, Web apis that conform to the REST design style are called RESTful apis. It defines resources from the following three aspects:

• Intuitively short resource addresses: URIs, such as:http://example.com/resources/; Each URI represents a resource;
• Transferred resources: The types of Internet media received and returned by the Web service, such as JSON, XML, YAML, etc.
• Operations on a resource: A set of request methods (such as POST, GET, PUT, or DELETE) supported by a Web service on that resource.

To a figure,

Typical APPLICATION of HTTP request methods in RESTful apis:

resources	GET	PUT	POST	DELETE
The URI of a set of resources, for examplehttp://example.com/resources/	Lists the URI and, optionally, the details of each resource in the resource group.	Replaces the current set of resources with the given set of resources.	Create/append a new resource to this group of resources. This operation usually returns the URL of the new resource.	Delete an entire group of resources.
The URI of a single resource, for examplehttp://example.com/resources/142	Gets the details of the specified resource in a format of your choice of the appropriate network media type (e.g., XML, JSON, etc.)	Replaces/creates the specified resource. Append it to the appropriate resource group.	Treats the specified resource as a resource group, and creates/appends a new element to it that belongs to the current resource.	Deletes the specified element.

REST of misunderstanding

REST was really ahead of its time in the year 2000. There is a lot of misunderstanding in the Web developer community about the design intent of HTTP, which leads to a lot of inefficient misuse of HTTP. This continued until the rise of Web 2.0 in 2005. At that time, DCOM, EJB, SOAP/WSDL and other DO style architectures were difficult to meet the constraints of distributed application architecture design in the Internet environment, which conflicted with the Architectural style of The Web itself, REST, and were difficult to be integrated into the Web. The so-called “Web Services” have nothing to do with the real Web, other than using HTTP as the underlying transport protocol.

It was only when Ruby on Rails, the famous Web development framework, began to support REST development that front-line Web developers really got to know REST. However, Rails supports REST development that limits operations on resources to THE SEMANTICS of CRUD (create, GET, modify, DELETE) (that is, mapping CRUD operations on resources to GET, POST, PUT, and DELETE HTTP methods), narrowing the scope of REST. Web development frameworks in other programming languages (e.g. Java’s Struts, Spring MVC, etc.) followed Rails’ lead in supporting REST development, however, leading Web developers to believe that: REST development is all about performing CRUD operations on resources through the HTTP methods GET, POST, PUT, and DELETE. There are even Web service apis that just use HTTP instead of SOAP and call themselves RESTful apis.

There were so many misconceptions about what a REST style really was, and so many touts of REST as a marketable buzzword, that Fielding, the creator of REST, had had enough. In October 2008 Fielding wrote a blog post that made a very clear claim: REST APIs must be Hypertext-driven! (REST apis must be hypertext-driven!) The idea of hypertext driving became an acronym, HATEOAS, derived from Fielding’s PhD thesis: hypermedia as the engine of application State. In fact, the concept of Hypertext Driven is the core concept of REST architecture style, is also the root cause of REST style architecture to achieve the goal of loose coupling.

REST design advances

When talking about REST Maturity, some people often refer to Richardson’s REST Maturity Model as the correct metric.

Level 1: Introduce the concept of resources into the architecture.

Most WS-* services and POX use only one URI as a service port and only one HTTP method to transfer data. This is equivalent to demoting HTTP from an application-layer protocol to a transport-layer protocol, and REST Field emphasizes that HTTP is an application protocol, not a transport protocol. Even better is to use multiple URIs, but different URIs serve only as different entry points for calls, while only using the same HTTP method to transfer data. Is one of the most common mistakes in the URI contains a verb, such as the URI http://example.com/getOrder?orderId=1234, actually “resource” is a kind of entity, so should be nouns, verbs should be placed in the HTTP protocol. Meanwhile the safety of the URI could also destroy the HTTP GET and curtain, such as a client at http://example.com/updateOrder?id=1234&coffee=latte GET (not POST), A new coffee order (a resource) can be created, and a GET request should not change any state of the service.

Level 2: Each URI represents a resource and supports HTTP verbs.

If multiple URIs are used in this case, different URIs must represent different resources. (Note that multiple URIs may refer to the same Resource, and one URI cannot refer to different resources.) And use multiple HTTP methods to operate on these resources simultaneously, for example, CRUD operations using POST, GET, PUT, and DELET respectively. In this case, both HTTP headers and payloads contain business logic, for example, HTTP methods correspond to CRUD operations, and HTTP status codes correspond to the status of operation results. Most of the So-Called RESTful apis we see today do just that. The translator of REST in Action also talks about how cruD-style Web services are enough for the unsavvy. Savvy people can thoroughly understand hypertext-driven, even reST-related semantic web, and ultimately reach the highest level of REST development.

According to Roy’s strict rules, hypermedia is a prerequisite for REST. Nothing else should claim to be REST. Explaining HATEOAS starts with explaining what hypermedia is: we already know what multimedia is and what hypertext is. The unique advantage of hypertext is hyperlink. If we introduce hyperlinks into multimedia, we have hypermedia, so the key role remains hyperlinks. Using hypermedia as application engine state means that application engine state changes are driven by clients accessing different hypermedia resources.

Let’s look at an example of a slightly different response:

GET https://api.example.com/profile

{
  "name": "Steve",
  "picture": {
    "large": "https://somecdn.com/pictures/1200x1200.png",
    "medium": "https://somecdn.com/pictures/100x100.png",
    "small": "https://somecdn.com/pictures/10x10.png"
  }
}
Copy the code

Because the link address is included in the response, clients using the API are free to choose what information to download. These links tell the client what options are available and where they are located. So instead of returning three different versions of the user profile image at the same time, all we do is tell the client that there are three available image sizes to choose from and where to find them. In this way, the client can make its own choices based on different scenarios. Also, if the client only needs images in one format, there is no need to download all three versions of the image. The result is a triple whammy: reduced network load, increased client flexibility, and increased API explorability.

The core concept of hypermedia is the so-called element, and these interconnected resources actually describe an agreement, a series of steps that lead us to a goal, such as ordering a cup of coffee, paying for it, picking up the coffee, and so on. This is the nature of hypermedia: by linking resources, we change the state of the entire application, that is, hypermedia transforms the state of distributed applications. It is important to note that representations of the state of the resource, not the state of the application, are exchanged between the server and the consumer, and the transferred representations include links reflecting the state of the application.

It is also recommended to look directly at the well-designed GitHub API to better understand the real RESTful apis and hyperMedia concepts.

Reference

• What Is REST? — Learn REST: A RESTful Tutorial
• What are RESTful implementations of REST and Go
• Understand RESTful architecture — Nguyen Yifeng
• How can REST architecture be understood graphically? – zhihu
• Simple reST-InfoQ
• Resource-oriented Architecture – RESTful Web Services Chinese Edition
• REST In Action
• What is RESTful? Read the REST in Practice
• Richardson Maturity Model — Martin Fowler
• Implementing hypermedia
• Making the API documentation