What is REST?

REST or REpresentational State transfer is a web service paradigm with the main principals:

Addressable resources 

Each resources within the system can be addressed by a unique URI.In the case of REST, a resources is data on the server that you want to expose a way to retrieve or manipulate. The data could be anything from a customer to the current time in London.

Although HTTP isn't required for REST I will focus on the use of HTTP as the transport layer for REST. To interact with a resources we need to access it though a URI, these are much like the URIs we use to access web pages . For example one resources URI could be

http://localhost:8080/platform/rest/customers?start=100&size=20

In this case the resources lists customers, and we can pass parameters to the resource to specify more information. Here we are telling the resource that we want 20 customers starting from the 100th customer.
These resources can be considered the nouns for REST, they define a person, place or thing. As such I try to use nouns as the URI path.

A standardized interface
There is a limited set of methods and operations that we can use to access our resources.

Expanding on the idea of nouns and verbs where the addressable resources URI was the noun the interface is the verb. In the case of HTTP we use GET, POST, PUT and DELETE. So with REST we don't want a URI

http://localhost:8080/platform/rest/createcustomer 

Since "createcustomer" is a verb, when we want resources to be nouns. Instead we would have URI

http://localhost:8080/platform/rest/customer

We would POST or PUT to the URI to tell the server that we want to create a new resource. This would then create a new resources

http://localhost:8080/platform/rest/customer/56743

If we call that URI with the GET operation we would get the details for the customer with the ID 56743, and if we want to update that customer we would call POST to the same URI. So the same URI can have different actions depending on the verb.

Self-descriptive messages

Each request to the server specifies the media type that it produces and consumes such that a single resource can handle different formats. Such as JSON for java script or XML for Flex applications

Communicate Stateless

Each request must provide sufficient information, so the server can respond to it without needing client session state on the server.

There is no client state held in the server, only the state each resources that the client accesses. So each request to the server should contain everything the server needs to fulfill the request. For example, when we sent the request to the server

http://localhost:8080/platform/rest/customers?start=100&size=20

Instead of the server remembering where we are in the list of customers. We tell the server what resources we need based on our clients state. This also implies that for secure resources we need to send authentication information with each request, since the server does not have a session. In later posts I will cover how I managed these constraints.


Hypermedia as the engine of application state (HATEOAS)

Clients discover the resources and interfaces available to them from the server not from fixed hardcoded paths.

This is an area that my rest platform is weak on, but let's look at an example. Lets say we request some information on a customer from URI

http://localhost:8080/platform/rest/customer/56743

This returns an XML document:

<customerTrans customerId="56743>
    <personaName>Colin</personaName>
</customerTrans>

After receiving the response we may want to perform further operations on this customer such as adding them as a friend. Based on the response we got back we would have to know the hard coded URI to add the customer as a friend. But using HATEOAS, when we get the original response for the customer it tells us all the operations we can do on it.

Such as:

<customerTrans customerId="56743">
    <personaName>Colin</personaName>
    <link rel="addFriend" method="post
        href="http://localhost:8080/platform/rest/friend/56743" />
</customerTrans>

If this user was already a friend maybe we would get back a different set of URI's that allow us to remove friends and send messages.

<customerTrans customerId="56743">
    <personaName>Colin</personaName>
    <link rel="removeFriend" method="delete"
        href="http://localhost:8080/platform/rest/friend/56743" />
    <link rel="message" method="post"
        href="http://localhost:8080/platform/rest/mgs/56743" />
</customerTrans>

As you can see in the above example, we get URI's back from the server that tell the client what actions are possible.