Based on the same architectural pattern of the web, “REST” has a growing dominance of the SOA (Service Oriented Architecture) implementation these days. In this article, we will discuss some basic design principles of REST.
SOAP : The Remote Procedure Call Model
Before the REST become a dominance, most of SOA architecture are built around WS* stack, which is fundamentally a RPC (Remote Procedure Call) model.
Under this model, “Service” is structured as some “Procedure” exposed by the system. For example, WSDL is used to define the procedure call syntax (such as the procedure name, the parameter and their structure). SOAP is used to define how to encode the procedure call into an XML string. And there are other WS* standards define higher level protocols such as how to pass security credentials around, how to do transactional procedure call, how to discover the service location … etc.
Unfortunately, the WS* stack are getting so complicated that it takes a steep learning curve before it can be used. On the other hand, it is not achieving its original goal of inter-operability (probably deal to different interpretation of what the spec says).
In the last 2 years, WS* technology development has been slowed down and the momentum has been shifted to another model; REST.
REST: The Resource Oriented Model
REST (REpresentation State Transfer) is introduced by Roy Fielding when he captured the basic architectural pattern that make the web so successful. Observing how the web pages are organized and how they are linked to each other, REST is modeled around a large number of “Resources” which “link” among each other.
As a significant difference with WS*, REST raises the importance of “Resources” as well as its “Linkage”, on the other hand, it push down the importance of “Procedures”.
Unlike the WS* model, “Service” in REST is organized as large number of “Resources”. Each resource will have a URI that make it globally identifiable. A resource is “represented” by some format of “Representation” which is typically extracted by an idempotent HTTP GET.
The “resource representation” can also embed other URI which refers to other resources. This emulates an HTML link between web pages and provide a powerful way for the client to discover other services by traversing its links. It also make building SOA search engine possible.
On the other hand, REST down-play the “Procedure” aspect and define a small number of “action” based on existing HTTP Methods.
- To get a resource, use HTTP GET is used to get a representation of the resource
- To search for a resource, use HTTP GET to its parent container to get a set of references to matched resources
- To create a resource, use HTTP PUT if the client define the resource id. Otherwise, use HTTP POST to the parent container URL
- To modify a resource, REST use HTTP PUT with the new representation embedded inside the HTTP Body.
- To delete a resource, REST use HTTP DELETE.
- To get metadata of a resource, REST use HTTP HEAD.
Notice that in all these cases, the HTTP Body doesn’t carry any information about the “Procedure”. This is quite different from WS* SOAP where the request is always made using HTTP POST.
At the first glance, it seems REST is quite limiting in terms of the number of procedures that it can supported. It turns out this is not the case, REST allows any “Procedure” (which has a side effect) to use HTTP POST.
Effectively, REST categorize the operations by its nature and associate well-defined semantics with these categories (ie: GET for read-only, PUT for update, DELETE for remove, all above are idempotent) while provide an extension mechanism for application-specific operations (ie: POST for application procedures which may be non-idempotent).
URI Naming Convention
Since resource is usually mapped to some state in the system, analyzing its lifecycle is an important step when designing how a resource is created and how an URI should be structured.
Typically there are some eternal, singleton “Factory Resource” which create other resources. Factory resource typically represents the “type” of resources. Factory resource usually have a static, well-known URI, which is suffixed by a plural form of the resource type.
Some factory resource examples are …
http://xyz.com/books
http://xyz.com/users http://xyz.com/orders
“Resource Instance”, which are created by the “Factory Resource” usually represents an instance of that resource type. “Resource instances” typically have a limited life span. Their URI typically contains some unique identifier so that the corresponding instance of the resource can be located.
Some resource instance examples are …
http://xyz.com/books/4545
http://xyz.com/users/123
http://xyz.com/orders/2008/04/10/1001
If this object is a singleton object of that type, the id is not needed.
http://www.xyz.com/library
“Dependent Resource” are typically created and owned by an existing resource during part of its life cycle. Therefore “dependent resource” has an implicit life-cycle dependency on its owning parent.
When a parent resource is deleted, all the dependent resource it owns will be deleted automatically. Dependent resource use an URI which has prefix of its parent resource URI.
Some dependent resource examples are …
http://xyz.com/books/4545/tableofcontent
http://xyz.com/users/123/shopping_cart
Creating Resource
HTTP PUT is also used to create the object if the caller has complete control of assigning the object id, the request body contains the representation of the Object after successful creation.
Request
PUT /library/books/668102 HTTP/1.1
Host: www.xyz.com
Content-Type: application/xml
Content-Length: nnn
<book>
<title>Restful design</title>
<author>Ricky</author>
</book>
Response
HTTP/1.1 201 Created
If the caller has no control in the object id, HTTP POST is made to the object’s parent container with the request body contains the representation of the Object. The response body should contain a reference to the URL of the created object.
Request
POST /library/books HTTP/1.1
Host: www.xyz.com
Content-Type: application/xml
Content-Length: nnn
<book>
<title>Restful design</title>
<author>Ricky</author>
</book>
Response
HTTP/1.1 301 Moved
Permanently Location: /library/books/668102
To create a resource instance of a particular resource type, make an HTTP POST to the Factory Resource URI. If the creation is successful, the response will contain a URI of the resource that has been created.
To create a book …
Request
POST /books HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<book>
<title>...</title>
<author>Ricky Ho</author>
</book>
Response
HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: /books/4545
<ref>http://xyz.com/books/4545</ref>
To create a dependent resource, make an HTTP POST (or PUT) to its owning resource’s URI
To upload the content of a book (using HTTP POST) …
Request
POST /books/4545 HTTP/1.1
Host: example.org
Content-Type: application/pdf
Content-Length: nnnn
{pdf data}
Response
HTTP/1.1 201 Created
Content-Type: application/pdf
Location: /books/4545/content
<ref>http://xyz.com/books/4545/tableofcontent</ref>
HTTP POST is typically used to create a resource when its URI is unknown to the client before its creation. However, if the URI is known to the client, then an idempotent HTTP PUT should be used with the URI of the resource to be created. For example,
To upload the content of a book (using HTTP PUT) …
Request
PUT /books/4545/tableofcontent HTTP/1.1
Host: example.org
Content-Type: application/pdf
Content-Length: nnnn {pdf data}
Response
HTTP/1.1 200 OK
Finding Resources
Make an HTTP GET to the factory resource URI, criteria pass in as parameters. (Note that it is up to the factory resource to interpret the query parameter).
To search for books with a certain author …
Request
GET /books?author=Ricky HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Response
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<books>
<book>
<ref>http://xyz.com/books/4545</ref>
<title>...</title>
<author>Ricky</author>
</book>
<book>
<ref>http://xyz.com/books/4546</ref>
<title>...</title>
<author>Ricky</author>
</book>
</books>
Lookup a particular resource Make an HTTP GET to the resource object URI Lookup a particular book…
Request
GET /books/4545 HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Response
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<book>
<title>...</title>
<author>Ricky Ho</author>
</book>
In case the resource have multiple representation format. The client should specify within the HTTP header “Accept” of its request what format she is expecting.
Lookup a dependent resource
Make an HTTP GET to the dependent resource object URI Download the table of content of a particular book…
Request
GET /books/4545/tableofcontent HTTP/1.1
Host: xyz.com
Content-Type: application/pdf
Response
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: nnn
{pdf data}
Modify a resource
Make an HTTP PUT to the resource object URI, pass in the new object representation in the HTTP body
Change the book title …
Request
PUT /books/4545 HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<book>
<title>Changed title</title>
<author>Ricky Ho</author>
</book>
Response
HTTP/1.1 200 OK
Delete a resource
Make an HTTP DELETE to the resource object URI
Delete a book …
Request
DELETE /books/4545 HTTP/1.1 Host: xyz.com
Response
HTTP/1.1 200 OK
Resource Reference
In some cases, we do not want to create a new resource, but we want to add a “reference” to an existing resource. e.g. consider a book is added into a shopping cart, which is another resource.
Add a book into the shopping cart …
Request
POST /users/123/shopping_cart HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<?xml version="1.0" ?>
<add>
<ref>http://xyz.com/books/4545</ref>
</add>
Response
HTTP/1.1 200 OK
Show all items of the shopping cart …
Request
GET /users/123/shopping_cart HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Response
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<?xml version="1.0" ?>
<shopping_cart>
<ref>http://xyz.com/books/4545</ref>
...
<shopping_cart>
Note that the shopping cart resource contains “resource reference” which acts as links to other resources (which is the books). Such linkages create a resource web so that client can discovery and navigate across different resources.
Remove a book from the shopping cart …
Request
POST /users/123/shopping_cart HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<?xml version="1.0" ?>
<remove>
<ref>http://xyz.com/books/4545</ref>
</remove>
Response
HTTP/1.1 200 OK
Note that we are using HTTP POST rather than HTTP DELETE to remove a resource reference. This is because we are remove a link but not the actual resource itself. In this case, the book still exist after it is taken out from the shopping cart.
What if the book itself is deleted ? In this case, all the shopping cart that refers to that book need to be fixed in an application specific way. One way is to do lazy checking. In other words, wait until the shopping cart checking out to check the book existence and fix it at that point.
Checkout the shopping cart …
Request
POST /orders HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<?xml version="1.0" ?>
<ref>http://xyz.com/users/123/shopping_cart</ref>
Response
HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: /orders/2008/04/10/1001
<?xml version="1.0" ?>
<ref>http://xyz.com/orders/2008/04/10/1001</ref>
Note that here the checkout is implemented by creating another resource “Order” which is used to keep track of the fulfillment of the purchase.
Asynchronous Request
In case when the operation takes a long time to complete, an asynchronous mode should be used.
In a polling approach, a transient transaction resource is return immediately to the caller. The caller can then use GET request to poll for the result of the operation
We can also use a notification approach. In this case, the caller pass along a callback URI when making the request. The server will invoke the callback URI to POST the result when it is done.
In the polling approach, the basic idea is to immediately create a “Transaction Resource” to return back to the client. While the actual processing happens asynchronously in the background, the client at any time, can poll the “Transaction Resource” for the latest processing status.
Lets look at an example to request for printing a book, which may take a long time to complete
Print a book Request
POST /books/123 HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<?xml version="1.0" ?>
<print>http://xyz.com/printers/abc</print>
Response
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Location: /transactions/1234
<?xml version="1.0" ?>
<ref>http://xyz.com/transactions/1234</ref>
Note that a response is created immediately which contains the URI of a transaction resource, even before the print job is started. Client can poll the transaction resource to obtain the latest status of the print job.
Check the status of the print Job …
Request
GET /transactions/1234 HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Response
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<transaction>
<type>PrintJob</type>
<status>In Progress</status>
</transaction>
It is also possible to cancel the transaction if it is not already completed.
Cancel the print job Request
POST /transactions/1234 HTTP/1.1
Host: xyz.com
Content-Type: application/xml; charset=utf-8
Content-Length: nnn
<?xml version="1.0" ?>
<cancel/>
Response
HTTP/1.1 200 OK
Conclusion
The Resource Oriented Model that REST advocates provides a more natural fit for our service web. Therefore, I suggest that SOA implementation should take the REST model as a default approach.
Popularity: 35% [?]
Fri, Nov 6, 2009
RickyHo