Adventures in the programming jungle

While I reading a book, I like to make a summary of every chapter, it force me to find and highlight the main ideas.  This post is about RESTful Web Services book.

Chapter 1: The Programmable Web and Its Inhabitants

This chapter is a global introduction to web services. The author introduce 3 types of web services architectures using the following criteria:

• how the web service clients send to the server the action that should be done. This kind of information is called “method information”

• how the web service clients send to the server on which data the server must work to compute an answer.This kind of information is called “scoping information”.

Using these two criteria, the web services can be of three types:

• Remote Procedure Call (RPC) web services. In this case the “method information” and the “scoping information” are stored into a SOAP envelope and the HTTP envelope is used only to transport the SOAP request/response.
• Resource Oriented (RESTful) web services. In this case the “method information” goes into the HTTP method. If the client wants to retrieve some information the GET HTTP method is used, the DELETE HTTP method is used if it wants to delete some infornation, etc.. The “scoping information” goes into the URI path.
• Hybrid web services. Some parts of hybrid web services are RESTful (in most cases, the parts that implies the retrieving of the information from the server) and some other parts are RPC style.

Chapter 2: Writing Web Service Clients

The goal of this chapter is to write web service clients in different programming languages against the del.icio.us web service.
So, any basic web service client must follow the next steps for fulfill his mission:

• create the HTTP request containing the request for the server.
• parse the response of the server.

For every step of the work flow, the author presents code samples for the following languages (Ruby, Python, Java, PHP, C# and JavaScript).

For the first step of the work flow (the creation of the HTTP request) a detailed explanation of external libraries that are used by the web service client is made. For the Ruby language, the rest-open-uri is used; for the Python the httplib2 (http://bitworkin.org/projects/httplib2/) is used; for the Java the Jakarta HttpLib (http://jakarta.apache.org/commons/httpclient/) is used; for C# the standard System.Web.HTTPWebRequest is used; for PHP the libcurl is used.

For the parsing part (the second step of the work flow) the different kinds of parsers are explained: DOM parsers, SAX parsers and “pull” parsers.

Chapter 3: What Makes RESTful Services Different?

In this chapter the author creates a client for a real REST web service. The REST service used is the S3 Amazon web service. S3 is based on two concepts: S3 “buckets” and S3 “objects”.An object is a named piece of data with some accompanying metadata. A bucket is a named container for objects.
To prove that S3 is a RESTful web service here are the resources and their method:

• the bucket list(/); use GET
• a bucket(/{bucket}); – use GET to list he bucket objects
• use POST to create the bucket
• use DELETE to delete the bucket
• an object(/{bucket}/{object}); – use GET to list the object metadata and value
• use HEAD to get the object’s metadata
• use PUT to set the object’s values and   metadata
• use DELETE to remove the object from the bucket

Chapter 4: The Resource-Oriented Architecture

For the author the ROA (Ressource Oriented Architecture) is an architecture that follow the RESTful criterias applied the world wide web. So, ROA is REST for WWW.
The ROA contains four concepts:

• resources
• resources names (URIs)
• resource representations
• the links between resources

and four properties:

• addressability
• statelessness
• connectedness
• a uniform interface

The heart of ROA are the resources, a client will create, read, update and delete resources.A resource can be anything, with the condition to be addressable by Web, so any ROA resource must have at least one URI. The relation between resources and URIs is one to many, a resource can be addressable by many URIs but a URI addresses only one resource. The statelessness is quite easy to assure because the HTTP protocol is stateless by default and every state needed should be handled by the application not by the REST service.
The resources can be presented in multiple forms, “simple” information (i asked a photo from a service or a text file) or “complex” information that can contains HTTP forms and, or HTTP links.

As in the case of a programming API, the way of working with the resources should be universally accepted. On a resource it is possible to execute 4 actions, CRUD (Create Read Update Delete). ROA uses the HTTP basic methods as an interface for the actions to execute on the resources:

• HTTP GET is used to retrieve a representation of a resource
• Create a new resource: HTTP PUT to a new URI and HTTP POST to an existing URI
• Modify an existing resource: HTTP PUT to a existing URI
• Delete an existing resource: HTTP DELETE

Chapter 5: Designing Read-Only Resource-Oriented Services

The procedure of creating a read-only resource-oriented service contains the following steps:

• Analyze the data set to be exposed s read-only resource

• Split the data set into resources

For each resource:

• Name the resources with URIs
• Design the representation served to the client
• Link the resource with other resources using hyper links and forms
• Consider the typical course of events
• Consider the error conditions: what to send to the client when the things goes wrong.

To show how all this criterias can be applied the author takes as example a service that serves informations about maps. The main difference between this service and the real world web application is that this service main clients will be other web services not only a human user.

The data set of the service will be maps, points of the maps, points having specific properties (name, description, place type).Basically the service will expose 2 kinds of resources: predefined data set (the USA country, the Paris city, any point an a map by the coordinates) and algorithmically-generated resources(towns in France with population less than 10 000, pizza restaurants near Mount Rushmore).
Now that we have the resources that we want to expose,it must find a way of naming the resources in order to be accessible by the clients. As we already said, the ROA use the WWW to make available the resources (see the review of the previous chapter) so the names will be based on URIs.
The organize the resource as URIs the following rules are used:

1. To encode an hierarchy the path variables will be used. ex: /parent/child
2. To encode resource that are not hierarchical the punctuation characters are used. ex: /parent/child1;child2
3. For the algorithmically-generated resources the query variable are used. ex: /search?query=country=france&population=1000

The sources are represented as XHTML documents that can be very easy interpreted by a browser in order to be used by a human and also by another web service. When a client is asking for a resource, the service sends an XHTML document containing more than the URI of the resource; the response can contains another URIs (places that are around the resource) or another type of informations like the description of the resource. In the case of algorithmically-generated resources, a HTML form is used to send to the service the parameters needed to compute the resource.

To inform the client about the state of the resource that he asked the standard HTTP headers are used. A 200 (“OK”) code response code means the resource was found, codes like 500 (“Internal Server Error”) will inform the client that the server have a problem, 404 (“Not Found”) code will inform the client that a place does not exist and a 400 code. The main idea is that it is possible to ‘play’ with the variety of HTTP response codes to send to a client a “business tailored” responses.