Skip to content

RESTful Web Services

Jump to bottom
dazoakley edited this page Sep 13, 2010 · 1 revision

This page aims to give general informations about RESTful web services and the HTTP protocol. Here, you will find necessary information to understand the architecture we use to provide our data.

Definition and Concepts

Web services consist of communication between clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources:

  • A resource can be essentially any coherent and meaningful concept that may be addressed (by an URL).
  • A representation is typically a document that captures the current state of a resource.

REST is an architecture style, not a standard like HTTP, HTML or CSS – it is a way of designing URLs that address resources. The idea is to give each data a unique URL as identifier and each URL addresses only one resource. Then, URLs should be intuitive to the point where they are easy to guess. One way to achieve this is to define directory structure-like URLs.

For example:
library/books/biology/ → We are requesting for the books that have “biology” for theme.

Then we might guess that a request to the URL library/books/programming/ will give us the books that have “programming” for theme.

RESTful Web Services are Stateless

Each request from client to server must contain all the information necessary to understand the request, and cannot take advantage of any stored context on the server. Therefore, authentication details (if required) have to be sent along with each request.

Accessing Resources

Usually, URLs are designed in this way:

URL Resource requested
books/ a collection of books
books/12/ an entry in the books collection, identified by the id 12

Retrieving Representations

The server responds to a request by giving you a representation of the resource you ask for. Each resource can be rendered in different representations. A web application is usually made to access data through a web browser. Therefore, the server response may be a HTML representation by default. However, it is also possible to ask for a specific representation, XML or JSON for example. Good practice in REST designs is to append to the URL the type of reprensentation you would like to get:

URL Response
books/ HTML representation of the books collection
books/12/ HTML representation of book entry having id 12
books.xml XML representation of the books collection
books/12.xml XML representation of book entry having id 12
books/12.json JSON representation of book entry having id 12

Notice: web applications do not all provide every representations. Some only provide HTML and XML, others only JSON.

HTTP Methods – Handling Data

HTTP protocol allows you to handle data through 4 methods: GET (Retrieve), POST (Create), PUT (Update), and DELETE (Delete). Depending on the method used to request a URL, the server response will be different:

HTTP Method URL Data (client) Response (server)
GET books/ HTML: book collection
GET books.xml XML: book collection
GET books/152 HTML: book entry (id 152)
POST books.json 
<?xml version="1.0"?>
<book>
  <name>REST Web Services</name>
</book>
 JSON: book entry (new id)
PUT books/152 
<?xml version="1.0"?>
<book id="152">
  <name>New title</name>
</book>
 HTML: book entry (id 152)
DELETE books/152 HTML: books collection

Notice: the 4th row (POST) demonstrates how you can create a new book by sending data as XML and asking for a JSON response at the same time.

Clone this wiki locally