jump to navigation

Advanced REST November 13, 2009

Posted by Terry.Cho in Uncategorized.
Tags: ,
add a comment

The basic concepts of REST were covered in Chapter 1. Still REST can be implemented in a more advanced version if utilizing the merits of HTTP.I would like to explain about the advanced REST in this Chapter with an example by using http://www.infoq.com/articles/subbu-allamaraju-rest .Let’s assume that the business scenario is making an account transfer from a bank.

1. Implementing an account transfer scenario through internet banking

STEP 1. Log-in to the internet banking system.

STEP 2. View the list of accounts of the relevant user through user ID.

http://bank.org/accounts?findby=7t676323a

200 OK
Content-Type: application/xml;charset=UTF-8
<accounts xmlns=”urn:org:bank:accounts”>
<account>
<id>AZA12093</id>
<customer-id>7t676323a</customer-id>
<balance currency=”USD”>993.95</balance>
</account>
<account>
<id>ADK31242</id>
<customer-id>7t676323a</customer-id>
<balance currency=”USD”>534.62</balance>
</account>
</accounts>

Regarding user ID 7t76323a, the two accounts of AZA12093 and ADK31242 will be returned along with the balance in those accounts. As the user made inquiry on each account number, the details of each account will be http://bank.org/account/AZA12093

http://bank.org/account/ADK31242

STEP 3. To see the business scenario of making account transfer,

POST /transfers
Host: bank.org
Content-Type: application/xml;charset=UTF-8

<transfer xmlns=”urn:org:bank:accounts”>
<from>account:AZA12093</from>
<to>account:ADK31242</to>
<amount currency=”USD”>100</amount>
<note>RESTing</note>
</transfer>

100 USD is transferred from AZA12093 to ADK31242 through HTTP post. Upon a successful account transfer, the following result value will be returned.

201 Created
Content-Type: application/xml;charset=UTF-8
<transfer xmlns=”urn:org:bank:accounts”>
<from>account:AZA12093</from>
<to>account:ADK31242</to>
<id>transfer:XTA8763</id>
<amount currency=”USD”>100</amount>
<note>RESTing</note>
</transfer>

In this case, take careful note that the return value is not HTTP 200 but HTTP 201. As the account transfer takes place not immediately but afterwards through async, HTTP 201 Created (meaning that the account transfer request has been received) as well as Transfer Application No XTA8763 are returned.

STEP 4. To check the account transfer details after one day,

http://bank.org/check/XTA8763
GET /check/XTA8763
Host: bank.org
200 OK
Content-Type: application/xml;charset=UTF-8
<status xmlns=”urn:org:bank:accounts”>
<code>01</code>
<message xml:lang=”en”>Pending</message>
</status>

The relevant account transfer request is indicated in a pending status.

2. Implementing an account transfer scenario through internet banking using the advanced REST

At a glance, it seems like an advanced and well-developed REST, but actually cannot be called as a successful architecture with the real merits of REST incorporated.

REST should have the following features:

First, REST should be able to identify the resource by using URL.

Second, REST should be able to represent various approaches toward the resource by using many functions of the HTTP protocol – especially the HTTP Header. For example, the Message Exchange Pattern of Sync/Async type (Call Back using the correlation ID) as well as the Meta Data like ‘Last Update Time’ to use web cache should be defined in the HTTP Header. Also the input and output data format should be defined based on the contents type.

Third, REST should be able to represent the relation between resources or the status information of the current resource through a link.

Based on such features of REST, let’s develop the previously-created account transfer scenario again.

STEP 1. Log-in to the internet banking system.

STEP 2. View the list of accounts of the relevant user through user ID.

200 OK
Content-Type: application/vnd.bank.org.account+xml;charset=UTF-8
<accounts xmlns=”urn:org:bank:accounts”>
<account>
<id>AZA12093</id>
<link href=”http://bank.org/account/AZA12093&#8243; rel=”self”/>
<link rel=”http://bank.org/rel/transfer edit”  type=”application/vnd.bank.org.transfer+xml”  href=”http://bank.org/transfers”/&gt;
<link rel=”http://bank.org/rel/customer&#8221;
type=”application/vnd.bank.org.customer+xml”
href=”http://bank.org/customer/7t676323a”/&gt;
<balance currency=”USD”>993.95</balance>
</account>
<account>
<id>ADK31242</id>
<link href=”http://bank.org/account/ADK31242&#8243; rel=”self”/>
<link rel=”http://bank.org/rel/transfer&#8221;
type=”application/vnd.bank.org.transfer+xml”
href=”http://bank.org/transfers”/&gt;
<link rel=”http://bank.org/rel/customer&#8221;
type=”application/vnd.bank.org.customer+xml”
href=”http://bank.org/customer/7t676323a”/&gt;
<balance currency=”USD”>534.62</balance>
</account>
</accounts>

As explained above, a slightly different type of return value will appear. What to check first is the content-type. : application/vnd.bank.org.account+xml; the return type of content-type will be returned. First, +xml mean that the format of this document is xml. vnd.bank.org.account defines the structure of returned data. (One of the weak points of REST – undefined data type – can be resolved by assigning an ID to the unique name of XML schedule used as an input or output)

Another change is that the LINK part has been added. This LINK indicates how the status of the current resource can change and what kind of URL can be used for status change. Also, it can indicate the relations with another relevant resource and define the data type, which is returned upon calling, as content-type. If the data type and the relation with another resource are defined in the returned message, user will be able to understand how to use and the relation of the resource without referring to a separately defined service. Therefore such feature of REST is called a ‘self-descriptive message’.

<account>
<id>ADK31242</id>
<link href=”http://bank.org/account/ADK31242&#8243; rel=”self” type=”application/vnd.bank.org.account+xml”/>
<link rel=”http://bank.org/rel/transfer&#8221;
type=”application/vnd.bank.org.transfer+xml”
href=”http://bank.org/transfers”/&gt;
<link rel=”http://bank.org/rel/customer&#8221;
type=”application/vnd.bank.org.customer+xml”
href=”http://bank.org/customer/7t676323a”/&gt;
<balance currency=”USD”>534.62</balance>

In this case, there are 3 types of changes: Self, http://bank.org/rel/transfer and http://bank.org/rel/customer

Firstly http://bank.org/rel/transfer, which is an account, defines the relation with a “transferable account”. To make account transfer, send through http://bank.org/transfers URL and the return value will become application/vnd.bank.org.transfer+xml.

Secondly self indicates a more detailed information of the account itself. It can be inquired through http://bank.org/account/ADK31242 and the returned data type will be application/vnd.bank.org.account+xml.

Thirdly http://bank.org/rel/customer indicates the client information. It can be inquired through http://bank.org/customer/7t676323a and the returned data type will be application/vnd.bank.org.customer+xml.

STEP 3. Execute account transfer.

Send the following data to the URL that has been returned from STEP 2.

POST /transfers
Host: bank.org
Content-Type: application/vnd.bank.org.transfer+xml;charset=UTF-8
<transfer xmlns=”urn:org:bank:accounts”>
<from>account:AZA12093</from>
<to>account:ADK31242</to>
<amount currency=”USD”>100</amount>
<note>RESTing</note>
</transfer>

The return value is as follows.

201 Created
Content-Type: application/vnd.bank.org.transfer+xml;charset=UTF-8
<transfer xmlns=”urn:org:bank:accounts”>
<link rel=”self” href=”http://bank.org/transfer/XTA8763″/&gt;
<link rel=”http://bank.org/rel/transfer/from”type=”application/vnd.bank.org.account+xml”href=”http://bank.org/account/AZA12093″/&gt;
<link rel=”http://bank.org/rel/transfer/to” type=”application/vnd.bank.org.account+xml” href=”http://bank.org/account/ADK31242″/&gt;
<link rel=”http://bank.org/rel/transfer/status” type=”application/vnd.bank.org.status+xml” href=”http://bank.org/check/XTA8763″/&gt;
<id>transfer:XTA8763</id>
<amount currency=”USD”>100</amount>
<note>RESTing</note>
</transfer>

STEP 4. Check the status of the account transfer progress.

The status of the account transfer progress can be checked by using http://bank.org/check/XTA8763 which has been returned from STEP 3.

Conclusion

From this article, I tried to focus on defining the data types by using the content-type of HTTP as well as the relations between resources by using a link. Yet I haven’t found the “perfect” standardized design even though there are many REST related articles that embrace similar philosophies.

Of course, as shown in the aforementioned examples, the in/out data format can be defined based on the content-type. Although the out (return) data format can be defined based on the defined types in the link, still the input aren’t defined. Also according to other designs, there are ways to define the data type by defining the URL of the real XML scheme in the URL of XML namespace.

From a protocol point of view, a link can be used by defining the relations between resources. This approach sounds preferable but actually can create various constraints during the actual implementation.

This article only presents a mere example of REST design in a more advanced version by utilizing HTTP more efficiently. However, more considerations are required for a more practical REST design.

=======

Comment

Please kindly consider that this article covering the advanced style of REST design is yet an uncompleted version and needs to be supplemented with more feedback. I will try to introduce the advanced style – especially regarding LINK and data type – with more details next time. In my following article, you will be able to learn about how REST is actually implemented in JAVA.