Web Services ReST: Overview

Description Article
Table of Contents
Summary

Description of web services implemented according the REST architecture.

Description

What is it ?

The web-service follows the REST Architecture style and therefore usies HTTP requests for CRUD operations over resources available through the web.
A resource is an object that can be accessed over the WWW (document, image, etc) through a specific URL.

Each of the resources are independent and all the information to understand the request and return a response is contained in the HTTP message.

REST web services are light since no technology is required (e.g. SOAP) and the HTTP response is not embedded in any other (transport or other) protocol.

How is represented the resource ?

The resource representation is built on XML/JSON.

How to implement ?

A concrete implementation of REST web services follows four basic principles:

  • Use HTTP methods explicitly:

Use linearly protocol as defined by RFC 2616. This principle establishes a one-to-one mapping between create, read, update, and delete (CRUD) operations and HTTP methods.

  • Be stateless:

The request (on the client) includes within the HTTP headers and body of a request all of the parameters,
context, and data needed by the server-side component to generate a response.

  • Expose directory structure-like URIs:

The Web service URIs should be intuitive in a way that required little, if any, explanation or reference for a developer to understand what it points to and to derive related resources.

Some additional guidelines to make note of while thinking about URI structure for a RESTful Web service are:

  1. Hide the server-side scripting technology file extensions (.jsp, .php, .asp);
  2. Substitute spaces with hyphens or underscores (one or the other).
  3. Avoid query strings
  4. Instead of using the “404 Not Found” code if the request URI is for a partial path, always provide a default page or resource as a response.
  • Transfer XML, JavaScript Object Notation (JSON), or both

Simple representation of the resource

 

What is the Uri format ?

It is a convention to use noums (e.g. Employee) instead of verbs (GetEmployee) to refer resources. The verb used correspond to the actions to perform over the resources and each action is performed through an HTTP operation.

A resource is referred by its own URI and has an identification ID.

Example of simple requests:

  • http://www.acme.com/Employee/12345
  • http://www.acme.com/Employee/pt/12345

Examples of more complex requests with parameters

  • http://www.acme.com/Employee/pt/12345/xml
  • http://www.acme.com/Employee/12345/?iso=pt&format=xml

HTTP operations status code and error messages

On each request’s response the HTTP the status code must be verified in order to confirm if the request ended successfully or originated an error:

In case of success a status code of 2xxx should be sent in the response.
In case of failure a status code of 4xxx (client-side error) or 5xxx (server-side error) should be sent in the response.

The algorithm below ilustrates how the achieve the status code to return:

In case of an error the response should include an error description including:

  1. The application error code ;
  2. The internal error message occurred at server-side;
  3. A custom message to display at client-side

This error description can be formatted as XML, according the following schema:

<errorcode>LOG0001</errorcode>
<errormessage>Invalid user</errormessage>
<internalerrormessage></internalerrormessage>

Operations
HTTP Operation: Create a new resource

A HTTP POST must be sent:

1. The data representing the new resource (e.g. employee) instance is required to be sent by the client on the request, formatted as indicated on the request (XML or jSON);

2. The server reads the message body (XML or JSON format according the content-type header) and creates a new employee information in the data source;

3. The server returns current state of the employee to the client

Remarks

The current state of the resource (e.g. empoyee) created should be included in the response since during processement some employee-related data can be generated or changed at server-side.

How to do it
Request:

POST /employee/add HTTP/1.1
Host: http://localhost/employee/add
Content-Type: application/xml;type=entry;charset="utf-8"
<Employee>
  <FirstName>João</FirstName>
  <LastName>Seixas</LastName>
  <EmpCode>3550</EmpCode>
  <Designation>SSE</Designation>
</Employee>
Response:

HTTP/1.1 201 Created
Date: Fri, 7 Oct 2009 17:17:11 GMT
Content-Length: nnn
Content-Type: application/xml;type=entry;charset="utf-8"
<Employee>
  <Id>1233</<Id>
  <FirstName>João</FirstName>
  <LastName>Seixas</LastName>
  <EmpCode>3550</EmpCode>
  <Designation>SSE</Designation>
</Employee>
HTTP Operation: Update representation of an existing resource

A HTTP PUT must be sent:

1. The data representing the resource (e.g. employee) instance is required to be sent by the client on the request, formatted as indicated on the request (XML or jSON);

2. The server extracts the resource instance IDentifier from the URL;

3. The server then reads the message body (XML or JSON format according the content-type header) and updates the particular employee in the data source;

4. The server returns current state of the employeee to the client

How to do it
Request:

PUT /employee/1233/edit HTTP/1.1
Host: http://localhost/employee/1233/edit
Content-Type: application/xml;type=entry;charset="utf-8"
<Employee>
   <Id>1233</<Id>
  <FirstName>João</FirstName>
  <LastName>Seixas</LastName>
  <EmpCode>3550</EmpCode>
  <Designation>Analyst programmer</Designation>
</Employee>
Response:

HTTP/1.1 202 Accepted
Date: Fri, 7 Oct 2009 17:17:11 GMT
Content-Length: nnn
Content-Type: application/xml;type=entry;charset="utf-8"
<Employee>
  <Id>1233</<Id>
  <FirstName>Anshu</FirstName>
  <LastName>Dutta</LastName>
  <EmpCode>3550</EmpCode>
  <Designation>Analyst programmer</Designation>
</Employee>
HTTP Operation: Retrieve the representation of an existing resource

A HTTP GET must be sent:

1. The resource (e.g. employee) IDentifier is sent by the client on the URL;

2. The server extracts the resource instance IDentifier from the URL;

3. The server then returns the resource information for that particular employee from the data source;

4. The server returns current state of the employeee to the client in the format requested in the URL ( XML or JSON)

How to do it
Request:

GET /employee/1233/show/xml HTTP/1.1
Host: http://localhost/employee/1233/show/xml
Response:

HTTP/1.1 200 OK
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/xml;type=entry;charset="utf-8"
<Employee>
  <Id>1233</<Id>
  <FirstName>João</FirstName>
  <LastName>Seixas</LastName>
  <EmpCode>3550</EmpCode>
  <Designation>Analyst programmer</Designation>
</Employee>
HTTP Operation: Delete an existing resource

A HTTP DELETE must be sent:

1. The resource (e.g. employee) IDentifier is sent by the client on the URL;

2. The server extracts the resource instance IDentifier from the URL;

3. The server delete the specific resource instance on the data source;

4. The server then returns a response indicating if the operation completed successfully or terminated in error

Remarks

The response status code should be:
- 200 (OK) if the response includes an entity describing the status of the operation;
- 202 (Accepted) if the action has not yet been enacted; or
- 204 (No Content) if the action has been enacted but the response does not include a describing entity.

How to do it
Request:

DEL /employee/1233/del HTTP/1.1
Host: http://localhost/employee/1233/del
Response:

HTTP/1.1 204 No Content
Date: Fri, 7 Oct 2005 17:17:11 GMT
Resources and other HTTP operations, methods or verbs
How to do it

Sometimes, depending on the resource, the simple HTTP methods/verbs mapped to the CRUD operation over the resource, can appear to not be enough. Actions like:

  • user login
  • user logout
  • change password
  • add credit
  • etc

appears that can not be expressed within a RESTful architecture.

The solution involves the re-definition of the concepts involved in the project and new resources may appear, namelly:

For login and logout action a new Session resource can be considered. In order to change password the User resource  is required. etc