Synopse Open Source

Resource-based

Internet is all about getting data. This data can be in a format of web page, image, video, file, etc.
It can also be a dynamic output like get customers who are newly subscribed.
The first important point in REST is start thinking in terms of resources rather than physical files.

You access the resources via some URI, e.g.

• http://www.mysite.com/pictures/logo.png - Image Resource;
• http://www.mysite.com/index.html - Static Resource;
• http://www.mysite.com/Customer/1001 - Dynamic Resource returning XML or JSON content;
• http://www.mysite.com/Customer/1001/Picture - Dynamic Resource returning an image.

Unique Identifier

Older web techniques, e.g. aspx or ColdFusion, did request a resource by specifying parameters, e.g.

 http://www.mysite.com/Default.aspx?a=1;a=2&b=1&a=3

In REST, we add one more constraint to the current URI: in fact, every URI should uniquely represent every item of the data collection.

For instance, you can see the below unique URI format for customer and orders fetched:

Here, "dupont" and "smith" are used as unique identifiers to specify a customer.
In practice, a name is far from unique, therefor most systems use an unique ID (like an integer, an hexadecimal number or a GUID).

Interfaces

To access those identified resources, basic CRUD activity is identified by a set of HTTP verbs:

Then, at URI level, you can define the type of collection, e.g. http://www.mysite.com/Customer to identify the customers or http://www.mysite.com/Customer/1234/Orders to access a given order.

This combinaison of HTTP method and URI replace a list of English-based methods, like GetCustomer / InsertCustomer / UpdateOrder / RemoveOrder.

By Representation

What you are sending over the wire is in fact a representation of the actual resource data.

The main representation schemes are XML and JSON.

For instance, here is how a customer data is retrieved from a GET method:

 <Customer>
<ID>1234</ID>
<Name>Dupond</Name>
<Address>Tree street</Address>
</Customer>

Below is a simple JSON snippet for creating a new customer record with name and address:

 {Customer: {"Name":"Dupont", "Address":"Tree street"}}

As a result to this data transmitted with a POST command, the RESTful server will return the just-created ID.

Clearness of this format is one of the reasons why in mORMot, we prefer to use JSON format instead of XML or any proprietary format.

Stateless

Every request should be an independent request so that we can scale up using load balancing techniques.

Independent request means with the data also send the state of the request so that the server can carry forward the same from that level to the next level.