Basics of RESTful web services

As explained on the previous Service-Oriented architecture and web services article, conceptually, web services are software components provided through a network-accessible endpoint, where service consumers and providers use messages to exchange information. Technically, web services are implemented on various ways. The key element that differentiates these implementations is the messages’ format or the messaging protocols used to exchange information. SOAP as a communication protocol and REST as an architectural style, are two widely used solutions to build webservices. This article explains REST architecturally. The next tutorial post will dive into the details of using it.

What is REST

REST defines a set of architectural principles by which you can design web services that focus on a system’s resources, and on how resource states are addressed and transferred over HTTP by a wide range of clients written in different languages. Standing for Representational State Transfer, REST offers webservices that are representational, stateless, manageable in cache, and has a set of other properties that we’ll explain in the following section. It is considered in the last few years a predominant Web service design model and has mostly displaced SOAP- and WSDL-based interface design because it’s a simpler style to use. REST’S decoupled architecture, and lighter weight communications between producer and consumer, makes it a popular building style for cloud-based APIs, such as those provided by Amazon, Microsoft, and Google. When web services use REST architecture, they are called RESTful APIs or REST APIs.

How does REST APIs work ?

REST is based on the stateless communication protocol HTTP. HTTP requests are used in order to read and write data. Which implies that the four HTTP methods GET, PUT, POST and DELETE  are used in a REST webservice, for the purpose of performing the four CRUD operations Create, Read, Update and Delete. A concrete implementation of a REST webservice follows four basic principles:

1.  Based on ressources
   

   Every system uses resources. These resources can be pictures, video files, web pages, business information, or anything that can be represented in a computer-based system. REST webservices are based on resources, unlike other types of webservices that can be based on operations. In other words, REST webservices represent and expose resources. In a REST system, any information that can be the target of an hypertext link can be a resource. A RESTful service uses a directory hierarchy like human readable URIs to address its resources. The job of a URI is to identify a resource or a collection of resources. While the actual operation is determined by an HTTP verb, the URI should not expose anything about the operation or action. This enables us to call the same URI with different HTTP verbs to perform different operations.
   Let’s say we have a database of cars and we want to expose it to other applications to use it, a resource will be presented this way: http://MyService/Cars/2.This indicates “MyService/Resources/aResource”.

2. Representational
   

   A resource representation reflects the current state of a resource, and its attributes, at the time a client application requests it. Resource representations in this sense are mere snapshots in time. This could be as simple as a representation of a record in a database that consists of a mapping between column names and XML tags, where the element values in the XML contain the row values. Or, if the system has a data model, then according to this definition a resource representation is a snapshot of the attributes of one of the things in your system’s data model.
   Web services give client applications the ability to request a specific content type that’s best suited for them. They use the built-in HTTP Accept header, where the value of the header is a MIME type (JSON, XML and XHTML…).

3. Uses HTTP methods
   

   The first characteristic of a RESTful Web service is the explicit use of HTTP methods in a way that follows the protocol. This basic REST design principle establishes a one-to-one mapping between CRUD operations and HTTP methods. For, you use POST to create a resource on the server, GET to retreive a ressource, ect… The non-restful and unfortunate ways to use a GET method for example, are:
   • We either use the request URI in an HTTP GET request (usually identifies one specific resource) or include a set of parameters to the query string in a request URI to define the search criterias used by the server to find a set of matching resources.
   • Or, the unattractive way some web APIs take is triggering something transactional on the server—for example, to add records to a database. In these cases the GET request URI is not used properly or at least not used RESTfully. If the Web API uses GET to invoke remote procedures, it looks like this:

    GET adduser?name=Amal

   Obviously this is not the best way to use the GET HTTP methods,  because the adduser method supports a state-changing operation over HTTP GET. Put another way, the HTTP GET request above has side effects:
   A semantic problem of webservers being designed to respond to HTTP GET requests by retrieving resources that match the path and returning them in a response, not to add records to databases! And another problem of inviting web caching tools (crawlers) and search engines to make server-side changes untentionally whenever we trigger a change of a server-side state…

   To overcome this common problem, we use HTTP methods the restful way: we move the parameter names and values on the request URI into XML tags. The resulting tags, an XML representation of the entity to create, may be sent in the body of an HTTP POST whose request URI is the intended parent of the entity as follows:

   POST /users
   Host: myserver
   Content-type: application/xml
   </xml version="1.0">
     <user>
       <name>Amal</name>
     </user>
   

   The method above is exemplary of a RESTful request: proper use of HTTP POST and inclusion of the payload in the body of the request.

   A client application may then get a representation of the resource using the new URI:

   POST /users/Amal
   Host: myserver
   Accept: application/xml

   Using GET in this way is explicit because GET is for data retrieval only. GET is an operation that should be free of side effects.

   In a RESTful Web service, the verbs—POST, GET, PUT, and DELETE—are already defined by the protocol. And ideally, to keep the interface generalized and to allow clients to be explicit about the operations they invoke, the web service should not define more verbs or remote procedures, such as /updateuser or /adduser.

4. Stateless
   

   When using REST webservices, each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. There is no state about client session saved on client side. And the client is responsible for storing and handling all application state related information on client side. So a REST webservice shifts most of the responsibility of maintaining state to the client application. For example, in the request for a multipage result set, the client should include the actual page number to retrieve instead of simply asking for the next as shown in the following figure:Here the web service generates a response that links to the next page number in the set and lets the client do what it needs to in order to keep this value around. The web service also generates responses that indicate whether they are cacheable or not to improve performance by reducing the number of requests for duplicate resources. The client application in this case uses the Cache-Control response header to determine whether to cache the resource or not.
   Statelessness in REST improves performance by saving bandwidth and minimizing server-side application state.

Wrapping up

Exposing a system’s resources through a RESTful API is a flexible way to provide different kinds of applications with data formatted in a standard way. This article is about just the basics of RESTful APIs,if you want to explore these webservices more, follow up with the next tutorial  Developing RESTful webservices with JAX-RS  .