REST-based WEB services: the basics

Basis

REST defines a set of architectural principles that you can use to design a system-resource-centric WEB service, including how clients written in different languages process and transfer resource state over HTTP. If you consider the number of Web services it uses, REST has become the most important Web service design model in recent years. In fact, REST has a very large impact on the Web, and because of its ease of use, it has generally replaced SOAP and WSDL-based interface designs.

The concept of REST was 2000 by Roy Fielding at the University of California at Irvine during the academic paper "Architectural Styles and the Design of network-based software Architect Ures "(see Resources for a link to this paper) for the first time, his paper analyzes a series of software architecture principles that use WEB services as a distributed computing platform, and the REST concept presented here does not get so much attention. Many years later, the main framework for REST has begun to emerge, but it is still being developed, as it has been widely accepted in various platforms, such as JSR-311, which has become an integral part of java™6.

This article argues that the specific implementation of the most pure form of restful Web service that is attracting so much attention today should follow four basic design principles:

• Explicitly use the HTTP method.
• No status.
• The URI that exposes the directory structure.
• Transfer XML, JavaScript Object Notation (JSON), or both.

The following sections will detail these four principles and provide a technical rationale explaining why these principles are important to REST Web service designers.

Back to top of page

Explicitly using the HTTP method

One of the main characteristics of REST-based WEB Services is the explicit use of HTTP methods in a manner that follows the protocols defined by RFC 2616. For example, an HTTP GET is defined as a data generation method designed to be used by client applications to retrieve resources to fetch data from a Web server, or to execute a query and expect the WEB server to find a set of matching resources and then use that resource to respond.

REST requires the developer to explicitly use the HTTP method, and is used in a manner consistent with the protocol definition. This basic REST design principle establishes a one-to mapping between creating, reading, updating, and deleting (create, read, update, and Delete,crud) operations and HTTP methods. Based on this mapping:

• To create resources on the server, you should use the POST method.
• To retrieve a resource, you should use the GET method.
• To change the state of a resource or update it, you should use the PUT method.
• To delete a resource, you should use the Delete method.

A regrettable design flaw inherent in many Web APIs is the use of HTTP methods for unintended purposes. For example, the request URI in an HTTP GET request typically identifies a specific resource. Alternatively, the query string in the request URI includes a set of parameters that define the search criteria that the server uses to find a matching set of resources. At a minimum, the http/1.1 RFC describes the GET method in this way. However, in many cases, an elegant Web API uses HTTP GET to trigger transactional operations on the server-for example, to add records to a database. In these cases, the GET request URI is used incorrectly, or at least not in a REST-based manner. If the Web API uses GET to invoke a remote procedure, it should look similar to the following:

GET /adduser?name=Robert HTTP/1.1

This is not a very elegant design because the Web method above supports state change operations over HTTP GET. In other words, the HTTP GET request has side effects. If the processing succeeds, the result of the request is to add a new user to the underlying data store-in this case Robert. The problem here is primarily semantic. Instead of adding records to the database, the WEB server is designed to respond to HTTP GET requests by retrieving resources that match the path (or query criteria) in the request URI and returning those resources or their representations in the response. From the perspective of the intended use of the Protocol method, and then from the perspective of a WEB server that is compatible with http/1.1, using GET in this way is inconsistent.

In addition to semantics, the other problem with GET is that in order to trigger deletion, modification, or addition of records in the database, or to change the server-side state in some way, it requests that the WEB caching tool (crawler) and search engines simply crawl through a link to make server-side changes unexpectedly. An easy way to overcome this common problem is to transfer the parameter names and values on the request URI to an XML tag. The resulting token is the XML representation of the entity to be created and can be sent in the body of the HTTP post, which is the expected parent entity of the entity (see listings 1 and 2):

Listing 1. Before

Get/adduser?name=robert http/1.1

Listing 2. After

Post/users http/1.1host:myservercontent-type:application/xml<?xml version= "1.0"?><user>  <name >Robert</name></user>

The above method is an example of a REST-based request: Use HTTP POST correctly and include the payload in the body of the request. On the receiving side, you can process the request by adding the resource contained in the body as a subordinate resource for the resource identified in the request URI, and in this case the new resource should be added as /users a subkey. The inclusion relationship between the new entity specified in the POST request and its parent entity is similar to how a file belongs to its parent directory. The client sets the relationship between the entity and its parent entity, and defines the URI of the new entity in the POST request.

The client application can then use the new URI to get a representation of the resource and at least logically indicate that the resource is /users under, as shown in Listing 3.

Listing 3. HTTP GET Request

Get/users/robert Http/1.1host:myserveraccept:application/xml

Using get in this way is explicit, because get is used only for data retrieval. GET is an operation that should have no side effects, that is, the so-called idempotent attribute.

Similar Web method refactoring needs to be applied when updating operations with HTTP GET is supported, as shown in Listing 4.

Listing 4. Update via HTTP GET

Get/updateuser?name=robert&newname=bob http/1.1

This changes the name attributes (or attributes) of the resource. Although the query string can be used for such operations, listing 4 is a simple example, but in the case of more complex operations, this pattern of querying strings as method signatures often crashes. Because your goal is to explicitly use the HTTP method, for the same reason described above (see Listing 5), a more restful approach is to send an HTTP PUT request to update the resource instead of sending an HTTP GET.

Listing 5. HTTP PUT Request

Put/users/robert http/1.1host:myservercontent-type:application/xml<?xml version= "1.0"?><user>  <name>Bob</name></user>

Using PUT instead of the original resource can provide a cleaner interface, which is consistent with the REST principle and the definition of the HTTP method. The PUT request in Listing 5 is explicit because it points to the resource by identifying the resource to be updated in the request URI, and it transmits the new representation of the resource from the client to the server in the body of the put request, instead of transferring the resource property as a loose collection of parameter names and values on the request URI. Listing 5 also has the Robert effect of renaming the resource from, which will Bob change its URI to /users/Bob . In the REST Web service, subsequent requests for that resource using the old URI will produce a standard 404 Not Found error.

As a general design principle, it is helpful to follow the REST guidelines for the explicit use of HTTP methods by using nouns instead of verbs in URIs. In a REST-based WEB service, the protocol has defined verbs (POST, GET, PUT, and DELETE). Ideally, the Web service should not define more verbs or remote procedures, such as or, in order to maintain the generalization of the interfaces and allow the client to clarify the operations they invoke. /adduser /updateuser This universal design principle also applies to the body of the HTTP request, which is designed to transport the resource state instead of carrying the name of the remote method or remote procedure to invoke.

Back to top of page

No status

REST Web services need to be scaled up to meet increasing performance requirements. Server clusters with load balancing and failover capabilities, proxies, and gateways are typically organized as a service topology, allowing requests to be routed from one server to another as needed to reduce overall response time for WEB service calls. To scale up with an intermediary server, the REST Web service needs to send a complete, stand-alone request, which means that the sent request includes all the data that needs to be met so that the components in the intermediary server can be forwarded, routed, and load balanced without having to store any state locally between requests.

A full, stand-alone request does not require the server to retrieve any type of application context or state when it processes the request. The REST Web Service application (or client) includes all the parameters, contexts, and data required by the server-side component to generate a response in the HTTP Header and request body. This lack of state can improve WEB service performance and simplify the design and implementation of server-side components because there is no state on the server, eliminating the need to synchronize session data with external applications.

Figure 1 illustrates a stateful service where an application might request the next page in a multi-page result set, and assume that the service tracks where the application left off when navigating the result set. In this stateful design, the service increments and stores variables in a location so that it previousPage can respond to requests for the next page.

Figure 1. Stateful design

A stateful service like this has become complicated. In Java Platform, Enterprise Edition (Java ee) environments, stateful services require a lot of pre-consideration to efficiently store session data and support session data synchronization throughout the Java EE container cluster. In such an environment, there is a very familiar problem with Servlet/javaserver Pages (JSP) and Enterprise JavaBeans (EJB) developers who often struggle to find java.io.NotSerializableException the source of the cause during session replication. Whether the exception was raised by the Servlet container during the HttpSession replication process or raised by the EJB container during stateful EJB replication, this is a problem that will cost developers a few days to try to find out in the graph of objects that make up the server state and are sometimes very complex Serializablethe object. Additionally, session synchronization increases the overhead that can affect server performance.

On the other hand, stateless server-side components are less complex and easy to design, write, and distribute across load-balanced servers. A stateless service not only performs better, but also transfers most of the state maintenance responsibilities to the client application. In a REST-based WEB service, the server is responsible for generating the response and providing an interface that enables the client to maintain application state on its own. For example, in a request for a multi-page result set, the client should include the actual page number to retrieve, rather than simply requiring the next page to be retrieved (see Figure 2).

Figure 2. Non-state design

A stateless Web service-generated response is linked to the next page number in the result set and allows the client to complete the required work to preserve this value. This aspect of REST-based WEB service design can be divided into two sets of responsibilities as a general separation to illustrate how to maintain stateless services:

Server

• Generates a response that includes a link to another resource so that the application can navigate between related resources. This type of response embeds a link. Similarly, if the request is for a parent or container resource, a typical REST-based response might also include a link to a child or subordinate resource of the parent resource so that the resources remain connected.
• Generates a response that indicates whether it can be cached to improve performance by reducing the number of requests for duplicate resources or by completely eliminating certain requests. The server achieves this by including the Cache-control and last-modified (date value) HTTP response headers.

Client application

• Use the Cache-control response Header to determine whether to cache the resource (creating a local copy of the resource). The client also reads the last-modified response header and sends the date value back in the If-modified-since header to ask the server if the resource has changed. This is called conditional get (Conditional get), with two headers at the same time, because the server's response is standard 304 code (not Modified), and if the requested resource has not changed since that time, the actual resource is omitted. HTTP Response Code 304 means that the client can safely use the cached local copy of the resource representation as the latest version, effectively skipping the subsequent GET requests until the resource changes.
• Send a complete request that can be serviced independently of other requests. This requires the client to take full advantage of the HTTP Header specified by the Web service interface and send the complete resource representation in the request body. The requests sent by the client rarely make assumptions about the previous request, the presence of a session on the server, the ability of the server to add context to the request, or the application state that is reserved between requests.

This collaboration between client applications and services is extremely important for the stateless nature of REST-based WEB services. It improves performance by saving bandwidth and minimizing server-side application state.

Back to top of page

Public Directory-Structured URI

From the perspective of the client application addressing the resource, the URI determines how intuitive the REST Web service will be and whether the service will be used in a way that the designer can predict. The third feature of a REST-based WEB service is fully URI-dependent.

The visual nature of the REST Web service URI should be easily guessed. The URI is considered to be an interface with its own documentation, and the developer can understand what it points to and get the relevant resources with little or no explanation or reference material. To do this, the structure of the URI should be simple, predictable, and easy to understand.

One way to achieve this level of availability is to define a directory-structured URI. Such URIs have a hierarchy whose root is a single path, and branching from the root is a sub-path to the primary aspect of exposing the service. By this definition, a URI is not just a slash-delimited string, but rather a tree of subordinate and ancestor branches that are joined together on a node. For example, in a discussion thread service that collects various topics from Java to newspapers, you might define a structured URI collection similar to the following:

http://www.myservice.org/discussion/topics/{topic}

/discussionthere is a node below the root /topics . There are a series of subject names under the node, such as gossip, technology, and so on, each of which points to a discussion thread. In this structure, it is easy to collect a discussion thread by simply entering something behind/topics/.

In some cases, the path to the resource is particularly appropriate for the directory structure. For example, a resource that is organized by date is an example of a resource that is well suited for using hierarchy syntax.

This example is very intuitive because it is based on rules:

http://www.myservice.org/discussion/2008/12/10/{topic}

The first path fragment is a four-digit year, the second path fragment is a two-digit date, and the third fragment is a two-digit month. It might be a little silly to explain it, but that's the simple level we're after. Humans and computers can easily generate structured URIs like this, because these URIs are based on rules. Filling in the path portion of the syntax gap is done because there is a clear pattern for combining URIs:

http://www.myservice.org/discussion/{year}/{day}/{month}/{topic}

Some additional guidelines to note when considering the URI structure of a REST-based WEB service include:

• Hides the server-side scripting technology file name extension (. jsp,. php,. asp)-If any, so that you can migrate to other scripting techniques without changing the URI.
• Keep all the contents lowercase.
• Replace spaces with hyphens or underscores (one or the other).
• Avoid querying strings as much as you can.
• If the request URI is used for a partial path, unlike using 404 Not Found code, the default page or resource should always be provided as a response.

The URI should also be static so that the link remains the same when the resource changes or the implementation of the service changes. This allows for bookmark functionality. It is also important that the relationship between the encoded resources in the URI is independent of how the resource relationship is represented in the location where the resource is stored.

Back to top of page

Transfer XML, JSON, or both

The resource representation typically reflects the current state of the resource and its properties when the client application requests the resource. The resource representation in this sense is just a snapshot of the time. This can be as simple as the record representation in the database, which includes a mapping between the column name and the XML tag, and the element value in the XML contains the row value. Or, if the system has a data model, according to this definition, the resource representation is a snapshot of the properties of one of the objects in the system's data model. These objects are the resources that you want your REST Web service to provide to clients.

The last set of constraints in REST-based WEB service design is related to the format of the data that the application and service Exchange in the request/response payload or HTTP body. It's really worth keeping everything simple, readable, and connected.

Objects in the data model are typically related in some way, and should reflect the relationship between the data Model objects (resources) in a way that represents the resources as they are transferred to the client application. In the discussion thread service, an example of a connected resource representation might include a root discussion topic and its properties, and an embedded link to the response provided for the topic.

Listing 6. Discusses the XML representation of threads

<?xml version= "1.0"? ><discussion date= "{date}" topic= "{topic}" >  <comment>{comment}</ comment>  <replies>    <reply from= "[email protected]" href= "/discussion/topics/{topic}/joe"/>    <reply from= "[email protected]" href= "/discussion/topics/{topic}/bob"/>  </replies></ Discussion>

Finally, to give clients the ability to request the specific content type that best suits them, the construction of your service should take advantage of the built-in HTTP Accept header, where the value of the Header is the MIME type. Some common MIME types used by REST-based services are shown in table 1.

Table 1. Common MIME types used by REST-based services

Mime-type	Content-type
Json	Application/json
Xml	Application/xml
Xhtml	Application/xhtml+xml

This enables services to be used by a wide variety of clients running on different platforms and devices and written in different languages. Using MIME types and HTTP Accept headers is a mechanism called content negotiation that allows clients to select the data format that is appropriate for them, and minimizes data coupling between the service and the application that uses the service.

Back to top of page

Conclusion

REST is not always the right choice. It becomes popular as a way to design Web services, which relies less on proprietary middleware (such as an application server) than on SOAP and WSDL. In a sense, REST is a regression to the Web before the era of large application servers by emphasizing early Internet standards such as URIs and HTTP. As you have already studied in the so-called REST-based interface design principles, XML over HTTP is a powerful interface that allows for easy connection of internal applications, such as a custom user interface based on asynchronous JavaScript + XML (Ajax) , locate, and use resources. In fact, the perfect match between Ajax and rest has added to today's attention to rest.

Exposing system resources through the REST-based API is a flexible way to provide data that is formatted in a standard way for different kinds of applications. It can help meet integration requirements, which are critical for building systems where you can easily assemble (Mashup) data, and help extend or build a basic REST-based service set to a larger collection. This article has only slightly touched on the basics, and hopefully the discussion in this article will induce you to continue exploring the topic.

http://www.ibm.com/developerworks/cn/webservices/ws-restful/

REST-based WEB services: the basics