InfoQ: Rest in a simple and comprehensible

I don't know if you realize that the "right" way to implement heterogeneous applications to application communications revolves around what is going on: while the current mainstream approach is clearly focused on the Web services domain based on SOAP, WSDL, and ws-* specifications, But there are also a handful of small but sonorous voices arguing that the better way is rest, the abbreviation for the state of expression transfer (representational states Transfer). In this article, I'm not going to go over the topic of contention, but try to make a practical introduction to rest and restful HTTP application integration. In my experience, some topics once touched on will lead to a lot of discussion, when it comes to the topic, I will elaborate in depth.

He was a term proposed by Roy Thomas Fielding in his paper the architectural Styles and the design of network-based Software architectures.

Rest itself is just an architectural style, not a standard, designed for distributed hypermedia systems.

(

Xiazdong Note:

1. According to the previous design pattern, many URLs are behind a bunch of parameters, for users is also very inconvenient, and rest is mainly concerned with the setting of the URL, the user's needs abstracted into resources;

2.REST Stateless: Session state is all saved by the client, server-side save resource state;

3.rest:representational State Transfer;

4.REST is not a standard, but a personal preference of the design pattern, each function as a resource;

5. If the client makes a request resource, it returns a form of representation of the resource (multiple representations);

6.HTTP is just a form of the unified interface for rest;

)

Rest key Principles

Most of the rest is introduced with its formal definition and background. But here and first, I'm going to make a simple and concise definition: Rest defines how you should use it correctly (which is quite different from how most people actually use it) Web standards, such as HTTP and URIs. If you stick to the rest principle while designing your application, you're going to get a system that uses a high-quality Web architecture that will benefit you. All in all, the five key principles are listed as follows: For all the "things" define IDs, link everything together. Unified Interface (Xiazdong Note: Each resource qualifies only 8 standard methods of HTTP) resource multiple representations (Html/xml/json) stateless communication: The client and server side do not have to save each other's details, and the server only needs to process the current request without having to know all the request history; because the state data cannot be saved in a shared context on the server, This increases the overhead of sending duplicate data in a series of request, which significantly reduces efficiency.

Let's take a closer look at these principles.

define IDs for all "things"

Here I use "things" instead of the more formal and accurate term "resources" because a simple principle should not be submerged in terminology. Think about the systems that people build, often finding a series of key abstractions that deserve to be identified. Everything should be identifiable and should have an obvious id--. In the Web, the unified concept of representing IDs is: URIs. URIs form a global namespace, and using URIs to identify your critical resources means they get a unique, global ID.

The main advantage of using a consistent naming convention for things (naming scheme) is that you don't need to put forward your own rules--it relies on a rule that has been defined, almost perfectly run around the world, and understood by most people. Think about any of the advanced objects (high-level object) in the last application you built (assuming it's not built in restful), it's quite possible to see many use cases that benefit from using unique identities. For example, if your application contains an abstraction of the customer, then I'm pretty sure that the user would want a link to a customer that could be emailed to a co-worker, or added to a browser bookmark, or even a piece of paper. More thoroughly: If in a similar Amazon.com online mall, not with a unique ID (a URI) to identify each of its products, imagine this will be how terrible business decisions.

When faced with this principle, many people are amazed at whether this means that database records (or database record IDs) need to be exposed directly to the outside world--and since many years of object-oriented practice has warned us that it's often scary to think of a few ideas, even if it's just a little thought. But there is no conflict between this principle and the hidden implementation details: Typically, things that deserve to be identified by a URI--resources--are more abstract than database records. For example, an order resource can consist of a single item, an address, and many other aspects that may not be expected to be exposed as separate identities. identifying all the things that are worth identifying , understanding this concept can further lead you to create resources that are uncommon in traditional application design: a process or process step, a sale, a negotiation, a quote request--all examples of things that should be identified. Again, this can lead to the creation of more persistent entities than the restful design.

Here are some examples of URIs you might think of:

http://example.com/customers/1234     //id=1234 's customer
http://example.com/orders/2007/10/776654   / In October 2007 id=776654 orders
http://example.com/products/4554    //id=4554 Merchandise
http://example.com/processes/ salary-increase-234   //Raise Salary

Just as I chose to create a convenient URI--a useful point of view, though not necessary for restful design--it should be easy to infer the meaning of the URI: they clearly identify a single "data item." But then look down:

Http://example.com/orders/2007/11

First of all, these two URIs look slightly different from the previous ones-after all, they are not the identification of one thing, but the identity of a set of things (assuming the first URI identifies all orders submitted in November 2007, and the second is a collection of green products). But these collections themselves are also things (resources) that should also be identified.

Note that the benefits of using unique, globally uniform naming conventions apply both to Web applications in browsers and to machine to machine (MACHINE-TO-MACHINE,M2M) communications.

To summarize the first principle: use a URI to identify all the things that are worth identifying, especially all the "advanced" resources provided in the application, whether they represent a single data item, a collection of data items, virtual or actual objects, or computed results.

link all things together

The next principle to be discussed has a somewhat frightening formal description: "Hypermedia is used as the application state engine (hypermedia as the engine of application states)", sometimes abbreviated to HATEOAS. (Strictly speaking, this is not what I said.) The core of this description is the Hyper-media concept, in other words: the idea of linking . Links are a common concept in HTML, but their usefulness is by no means limited to this (for people browsing the web). Consider the following fictional XML fragment:

<order self= "http://example.com/customers/1234" > 
   <amount>23</amount> 
   <product ref= " http://example.com/products/4554 "> 
   <customer ref=" http://example.com/customers/1234 "> 
</ Customer> </product></order>

If you look at the links between product and customer in a document, it's easy to imagine how an application (that has retrieved a document) will "follow" the link to retrieve more information. Of course, it is also possible to use a simple "id" attribute that adheres to a private naming convention as a link- but only within the context of an application. The elegance of a link with a URI is that it can point to resources from different applications, different servers, and even different companies on another continent-because the URI naming convention is a global standard and all the resources that make up the web can be interconnected.

The hyper-media principle has a more important aspect-the application of "state". In short, the server side (or, if you will, the service provider) provides a set of links for the client (the service consumer) to enable the client to change the application from one state to another through a link . We'll look at this in another article later, so just remember that linking is a very effective way to make a dynamic application.

The principle is summarized as follows: wherever possible, use links to guide the things that can be identified (resources). It is also the hyperlinks that make up the web today.

using standard methods

In the discussion of the first two principles there is a presumption that an application that receives a URI can explicitly do something meaningful through a URI . If you see a URI on the bus, you can enter it into the browser's address bar and return--but how does your browser know what to do with the URI?

The reason the browser knows how to handle URIs is that all resources support the same interface (get/post/...). ), a set of the same method (as long as you are willing to call it an operation). This is called the verb (verb) in HTTP, and in addition to the two well-known (get and post), the standard method collection also contains the put, DELETE, head, and options. The meaning of these methods is defined in the HTTP specification along with the behavior promise. If you are an OO developer, you can imagine that all resources in the restful HTTP scenario inherit from a class similar to this one (using Java, C # Pseudo syntax descriptions, note the key methods):

Class Resource {
     Resource (URI u);
     Response get ();
     Response Post (Request R);
     Response put (Request R);
     Response Delete ();

Because all resources use the same interface, you can use the Get method to retrieve a representation (representation)-that is, a description of the resource. Because the semantics of get is defined in the specification, it is certain that you do not have to be responsible for the consequences when you call it-that is why you can call this method "safely". The Get method supports very efficient, mature caching, so in many cases you don't even need to send a request to the server. It is also certain that the Get method has a power equal to the same result]--if you send a GET request without the result, you may not know whether the request failed to reach the destination or the response was lost on the way back. Idempotent guarantees that you can simply send one more request to solve the problem. Idempotent also applies to put (the basic meaning is "Update resource data, if the resource does not exist, create a new resource based on this URI") and delete (you can manipulate it over and over again until you come to the conclusion that there is no problem with deleting something that doesn't exist). The Post method, which usually means "create a new resource", can also be used to invoke any process, so it is neither secure nor idempotent.

If you expose the application function in a restful way (also known as a service function if you prefer), then this principle and its constraints apply to you as well . If you are accustomed to other design methods, it is difficult to accept this principle-after all, you probably think your application contains logic beyond the scope of these operations. Please allow me to take some time to convince you that there is no such situation.

Take a look at the following simple example of a procurement scenario:

As you can see, there are two service programs defined in the example (no implementation details are included). The interfaces of these service programs are tailored to accomplish tasks (the ordermanagement and customermanagement Services we discuss). If the client program attempts to use these services, it must encode these specific interfaces--it is not possible to use the client program to collaborate with destinations and interfaces before these interface definitions. These interfaces define the application Protocol (Application protocol) of the Service program.

In the restful HTTP approach, you will access the service program through a common interface that forms the HTTP application protocol . You might come up with a way like this:

You can see that specific actions in the Service program (list customers/...) is mapped to the standard HTTP method (Get/post) (note: through annotation mapping)--To eliminate ambiguity, I created a new set of resources. "This is a trick," I heard you shouting. No, it's not cheating. The Get method on the URI that identifies a customer is exactly equivalent to the getcustomerdetails operation. Some people illustrate this with a triangle:

Think of three vertices as buttons you can adjust. You can see that in the first approach, you have many operations, many kinds of data, and a fixed number of "instances" (essentially the same number of service programs that you have). In the second method, you have a fixed number of operations, many kinds of data, and many objects that call a fixed method. The point is that you can basically say anything you like in both ways.

Why it is so important to use standard methods. Fundamentally, it makes your application a part of the Web-the application's contribution to becoming the most successful application on the Internet to the web, in proportion to the amount of resources it adds to the web. With the restful approach, an application may add millions of customer URIs to the Web, and if CORBA is used and maintains the original design of the application, its contribution is probably just an "endpoint (endpoint)"-like a very small door, Only allow the person with the key to enter the resource domain.

The unified interface also enables all components that understand the HTTP application protocol to interact with your application. the generic client (generic client) is an example of the components that benefit from it, such as curl, wget, proxies, caching, HTTP servers, gateways, Google, Yahoo!, MSN, and so on.

The summary is as follows: to enable client programs to collaborate with your resources, resources should implement the default application protocol (HTTP) correctly, using standard get, PUT, post, and delete methods.

Multiple representations of resources

So far we've overlooked a slightly more complex question: how the client knows how to handle the retrieved data, such as the result of a GET or POST request. The reason for this is that HTTP takes the form of allowing separation of relationships between data processing and operational invocation. In other words, if the client knows how to handle a particular data format, it can interact with all resources that provide this presentation format. Let's use one more example to illustrate this point. With HTTP content negotiation, a client can request a representation of a particular format:

get/customers/1234 http/1.1
Host:example.com 
accept:application/vnd.mycompany.customer+xml  

The result of the request may be some customer information expressed in a company-specific XML format. Suppose the client sends another different request, as follows:

get/customers/1234 http/1.1
Host:example.com 

The result may be the customer address in the vcard format. (Here I don't show the content of the response, which should contain metadata about the data type in its HTTP Content-type header.) This explains why, ideally, a resource statement should be in a standard format--If the client is "aware" of the HTTP application protocol and a set of data formats, it can interact with any restful HTTP application in the world in a meaningful way. Unfortunately, we can't get the standard format for everything, but maybe we can think of using a standard format in a company or some partner to create a small environment. Of course, the above applies not only to data from the server to the client, but to the client, if the data from the client conforms to the application protocol, then the server can work with the data in a particular format without caring about the type of clients.

In practice, the multiple representations of resources have other important benefits: If you provide HTML and XML two representations of your resources, these resources can be used not only by your application, but also by any standard Web browser -that is, Your application information can be obtained by anyone who will use the web.

There is another way to use resource representations: You can incorporate the application Web UI into the Web API--after all, the API design is typically driven by the functionality that the UI can provide, and the UI performs the action through the API. Bringing the two tasks together brings surprising benefits, making it possible for both the user and the caller to get a better web interface.

Summary: Provide multiple representations of resources for different needs.

No State communication

stateless communication is the last principle I want to talk about. First, it should be emphasized that while rest contains a stateless (statelessness) concept, it does not mean that the application of the exposure function cannot be state-
In fact, in most cases this can lead to a whole practice that is of no use. The rest requirement status is either placed in the resource state or saved on the client. Or in other words, the server side cannot maintain the communication status of any client that is communicating with it other than a single request. The most straightforward reason to do this is scalability-if the server needs to maintain client state, a large number of client interactions can seriously affect the server's memory free space (footprint). (Note that it often takes a bit of redesign to do stateless communication--you can't simply place some session state on a URI, and then claim that the application is restful.) ）

In addition, other aspects may seem more important: stateless constraints make the server's changes invisible to the client because the client does not rely on the same server for two consecutive requests. A client receives a document from a server that contains a link. When it has to do some processing, the server is down, it may be the hard drive is damaged and be repaired, may be the software needs to upgrade reboot-if the client access to the link received from this server, it will not detect the backend server has changed.

the rest of the theory

I confess: The rest I have said is not real rest, and I may be a little too keen on simplicity. But because I wanted to have a different opening, I didn't introduce its formal definition and background at the outset. Now let's give a little brief introduction to this.

First of all, I didn't explicitly distinguish between HTTP, RESTful http, and rest before. To understand the relationship between these different aspects, we must first look at the history of rest.

Roy T. Fielding in his Ph. D. thesis (in fact, you should visit this link--at least for an academic paper, it's fairly readable.) This paper has been translated into Chinese) to define the term rest. Roy was one of the main designers of many basic web protocols, including HTTP and URIs, and he put a lot of ideas into these protocols in his paper. (This paper is known as the "Rest Bible", which is appropriate-after all, it was the author who invented the term, so any content he wrote on the definition was considered authoritative. In the paper, Roy first defines a methodology to talk about architectural style --advanced, abstract patterns, to express the core concepts behind the architectural approach. Each architectural style is formed by a series of constraints (constraints) definitions. Examples of architectural styles include "no style" (no constraints at all), Pipes and filters (pipe and filter), client/server, distributed objects, and--you guessed it--rest.

If this sounds too abstract to you, that's right.--rest is essentially a high-level style that can be implemented by many different technologies and can be instantiated-by assigning different values to its abstract attributes. For example, rest contains the concepts of resources and a unified interface-that is, all resources should respond to these same methods. But rest doesn't say which methods or how many methods.

One "Avatar" of the rest style is HTTP (and a set of related standards, such as URIs), or slightly more abstract: the Web architecture itself. Then, in the example above,HTTP uses the HTTP verb as an "instance" of the rest uniform interface. since Fielding is a restful style defined after the web has been (or at least is mostly) "perfected", one might argue that the two matches are 100%. But in any case, Web, HTTP, and URI as a whole are just one of the main implementations of the rest style. However, since Roy Fielding is the author of a rest paper and has far-reaching implications for Web architecture design, the similarity is understandable.

Finally, I used the term "RESTful HTTP" again and again for the simple reason that many applications using HTTP, for some reason, did not follow the rest principle, and some would say that using HTTP without the rest principle would be tantamount to abusing HTTP. Of course it sounds a little crazy--the fact that the rest constraints are actually violated is usually simply because the design tradeoffs of each constraint may not be appropriate for some particular case. Often, however, the reason for violating rest constraints can be attributed to a lack of awareness of its benefits. To see an obvious negative case: using an HTTP GET invocation is similar to deleting an object, which violates rest security constraints and general knowledge (the client should not be responsible for this, and the server-side developer may not be doing it intentionally). But in subsequent articles, I will mention more of this or that kind of misuse of HTTP.

Summary

This article attempts to provide a quick introduction to the concepts behind rest (Web architecture). RESTful HTTP exposure is not the same as RPC, distributed objects, and Web services; To really understand these differences requires a change of mindset. Whether you're building an application that simply exposes the Web UI or wants to make the API a part of the web, it's good to know the rest principle.

Stefan Tilkov is the lead editor for the Infoq SOA community and is located in Germany and Switzerland Innoq co-founder, chief advisor and rest fanatic leader of the company.

View English original : A Brief Introduction to REST