RESTful WEB Services

REST is an acronym for REpresentational State Transfer, this term is coined by Roy Fielding in his Ph.D. dissertation to describe an architecture design of networked systems. Below Roy Fielding’s explanation of the meaning of REST:

Representational State Transfer is intended to evoke an image of how a well-designed Web application behaves: a network of web pages (a virtual state-machine), where the user progresses through an application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use.

As you see, REST is an approach, not a standard, and he does not deal with implementation details. REST is one of architectural Web Services design. So, REST defines a set of architectural principles by witch you can build WS oriented resource. REST become in last year the predominant WS design model used in the globe, because it’s the simplest one.

Note that RESTful WS does not mean that the output should be in JSON format. This is a big conflict, the result can be in any format as JSON, XML. Personally, I prefer always to use JSON format.

REST Principles

A REST Web service is any Web service that follows four basic design principles:

In the following sections, I will try to explain each of these principles.

Use HTTP methods explicitly

REST Web services should using HTTP methods explicitly following the protocol definition. So, our web service should be consistent with the protocol definition. In fact we should use the appropriate HTTP method for every CRUD operations:

  • 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

Each request from the client should contains all the information needed for the Web service to understand it. This constraint improve the visibility, reliability, and scalability. This means that third-party as proxies in communication patterns (and this will increase scalability). Unfortunately, this will decrease network performance by increasing the repetitive data (per-interaction overhead) sent in a series of requests, since that data cannot be left on the server in a shared context.

Expose directory structure-like URIs

REST Web service URIs should be so intuitive that we can easily to guess, it should be self-documented. This type of URI should be hierarchical, rooted at a single path, and branching from it are subpaths that expose the service’s main areas. It’s also recommended to follow this guidelines:

  • Hide the server-side scripting technology file extensions (.jsp, .php, .asp)
  • Keep everything lowercase (even it’s inconsistent with W3C rule).
  • Substitute spaces with hyphens or underscores.
  • Avoid query strings as much as you can.

Transfer XML, JavaScript Object Notation

A resource representation should be in a standard format. The most format used in REST Web services are: XML, JSON, and HTML. This is where it really pays to keep things simple, and human-readable.