Introducing the Architecture REST - Creating APIs - Part 01

Hi all,

In this new series of posts I will talk about a architecture style widely used in web services for distributing simultaneously hypermedia content such as texts, images, videos, etc. The style is called REST (REpresentational State Transfer) where the term RESTful refers to the systems which follow the REST principles.


Introduction

Currently, companies like Yahoo, Amazon among others, are deeply using this technology, which became quite popular. One of the reasons to this success is the fact that you can easily create a client that uses the Amazon services or even access your Twitter Account by a simple application. 

Imagine if you have a web service or a social network and you want developers all around the planet to develop applications that communicate with your web service and use your data to develop new awesome ideas. By using REST architecture you can easily develop and deploy APIs for giving access to your data to outside applications, delivering new functionalities to the web community via an open API.

In this article and the next ones I will show a simple API that I developed and how I used the principles REST (HTTP response codes, methods, cache, cookies, security, tests) to implement it. The examples of codes presented here are using the library Python and the framework for Web Django.

Introducing the client/server protocol


REST is not an official standard, but an architecture style of networked systems consisting of clients and servers.  The idea behind it is that clients initiate the requests to the servers and then the servers process requests and return appropriate responses.

In the REST architecture, neither the client and server need to store the transitional states between the exchanged messages of request and response. This restriction isolates the client of the changes in the server side, since, between two requests, there is not connection client-server.  The client could receive data from the server, while the server is working on at the first request. Even if the second request restarts, the first connection would not realize what happened. In fact, the separation between client and server must be clear: One module works as the service provider the other one consumes this service as consumer.

REST uses the set of methods defined in the HTTP protocol, which the most known are POST and GET.  Adding the PUT and DELETE, we have a CRUD.  CRUD known as Create, Read, Update and Delete are the four basic functions of persistent storage. It is also considered a convention used to describe a user interface that facilitate viewing, searching and changing information. There are also more methods such as HEAD and OPTIONS, which  it will be explored in another post.

The Requests and responses in REST are built around the transfer of "representations" of "resources". A resource can be considered and concept that is addressed and it is the information elements of the REST architecture. Any information coherent and meaningful can be considered a  resource. Examples: Users, documents, images, another resources, etc.  Each resource has a set of methods as explained in the last paragraph.  A representation of the resource is typically a document that captures the current or intended state of a resource.

It is important to remind that the resources are thing, not actions, so the names used in the URI (the Uniform Resource Identifier), that is, the identity of the resource in the Internet, must be standardized as nouns. For instance, for a User resource, you should use for the method GET when requested the URI /user/{id}.  So it is not a pattern to map the URI as /user/getUser/{id} , since the basic operations - create, read , update and delete are defined logically by the methods HTTP.

REST x SOAP

The motivation behind REST web services follows the basic principle that drives the technology: "To make complex things simpler".  The first generation web services relied on exchanging XML packets conforming to SOAP (Simple Object Access Protocol) specification using HTTP protocol.  However, supporters of REST architecture consider SOAP and XML to be too heavy special when we deal with clients with limited capabilities such as mobile phones and tablets.  It is also common in REST services to use JSON (JavaScript Object Notation) as a convenient, "fat-free" alternative to XML. So clients running with browsers with embedded JavaScript logic would easily access REST resources in an asynchronous fashion AJAX for example.

The REST is interesting to use in the following situations:

• The WebServices are  totally stateless; 
• The storage in cache can be explored for performance;
• The producer and consumer of services have a mutual comprehension of the context and content of what is repassed;
• If the bandwidth is limited, for instance, in mobile devices with limited capabilities like tablets and mobile phones.

The SOAP is interesting to use when:

• A formal contract must be established to describe the interface that offers the web service. The WSDL (Web Service Description Language) describes the logic details such as messages, operations, call and location services in the web.
• If the architecture must follow complex non-functional requirements. Examples include transactions, security, addressing, coordenation as others. Most of the real world applications go beyond of the simple CRUD operations and require contextualized information and conversational states;
• The architecture must handle with asynchronous processing, invocation logic and other services and states. This is easily handled with BPM (Business Process Management).

REST Architecture vs SOAP Architecture

The REST architecture can also be considered a service-oriented architecture (SOA), which implements the basic principles of interoperability and weak coupling. In the next post we will explore in details those principles in REST.

References

• REST, Wikipedia
• Geeknizer, REST vs SOAP