RESTful Web Services

More than a decade after its introduction, REST has become one of the most important technologies for Web applications. Its importance is likely to continue growing quickly as all technologies move towards an API orientation. Every major development language now includes frameworks for building RESTful Web services.

Representational State Transfer (REST) is not an official standard, but rather a guideline to build an efficient framework for communication between two machines - client and servers. Clients initiate requests to servers; servers process requests and return appropriate response. Requests and responses are built around the transfer of "representations" of "resources". A resource can be essentially any coherent and meaningful concept that is addressed. A representation of resource is typically a document that captures the current or intended state of resource.

REST it is primarily used to build Web services that are lightweight, maintainable and scalable. A service based on REST is called a RESTful service. REST is not dependent on any protocol, but almost every RESTful service uses HTTP as its underlying protocol.

A concrete implementation of a RESTful WEB service follows four basic design principles:

  • Use HTTP methods explicitly.
  • Be stateless.
  • Expose directory structure-like URIs.
  • Transfer XML, JavaScript Object Notation (JSON), or both.

Use HTTP methods explicitly

REST asks developers to use HTTP methods explicitly and in a way that's consistent with the protocol definition. The basic REST design principle establishes a one-to-one mapping between create, read, update and delete (CRUD) operations and HTTP methods. According to this mapping:

  • To create a resource on the server, use POST.
  • To retrieve a resource, use GET.
  • To change the state of a resource or to update it, use PUT.
  • To remove or delete a resource, use DELETE.

Be stateless

REST Web services need to scale to meet increasingly high performance demands. Clusters of servers with load-balancing and failover capabilities, proxies and gateways are typically arranged in a way that forms a service topology, which allows requests to be forwarded from one server to the other as needed to decrease the overall response time of a Web service call. Using intermediary servers to improve scale requires REST Web service clients to send complete, independent requests; that is, to send requests that include all data needed to be fulfilled so that the components in the intermediary servers may forward, route and load-balance without any state being held locally in between requests. A complete, independent request doesn't require the server, while processing the request, to retrieve any kind of application context or state. A REST Web service application (or client) includes within the HTPP headers and body of request all of the parameters, context and data needed by the server-side component to generate a response.

Expose directory structure-like URIs

From the standpoint of client applications addressing resources, the URIs determine how intuitive the REST Web service is going to be and whether the service is going to be used in ways that the designers can anticipate.

REST Web service URIs should be intuitive to the point where they are easy to guess. Think of a URI as a kind of self-documenting interface that requires little, if any, explanation or reference for a developer to understand what it points to and to derive related resources. Structure of a URI should be straightforward, predictable and easily understood.

Transfer XML, JSON or both

A resource representation typically reflects the current state of a resource and its attributes, at the time a client application request it. Resource representations in this sense are mere snapshots in time. This could be a thing 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 definitiona a resource representation is a snapshot of the attributes of one of the things in data model.

One way to achieve this level of usability is to define directory structure-like URIs. This type of URI is hierarchical, rooted at a single path and branching from it are subpaths that expose the service's main areas.

In our application we will use JSON for its inherent javascript support allowing most browsers to process it easily. Apart from that, the XML format is verbose and takes time to parse and also creates an impedance mismatch when converting to and from a POJO.