Java Reference
In-Depth Information
Reduced state transition errors
Links are not used only as a mechanism to aggregate and navigate information. They can
also be used to change the state of a resource. Consider an order in an ecommerce website
obtained by traversing the URI
/orders/333
:
<order
<order id=
"333"
>
<customer
<customer id=
"123"
>
...
</customer>
</customer>
<amount>
</amount>
<order-entries>
<amount>
$99.99
</amount>
<order-entries>
...
</order-entries>
</order-entries>
</order>
</order>
Let's say a customer called up and wanted to cancel her order. We could simply do an HTTP
DELETE on
/orders/333
. This isn't always the best approach, as we usually want to retain
the order for data warehousing purposes. So, instead, we might PUT a new representation of
the order with a
cancelled
element set to
true
:
PUT
/orders/333
HTTP
/
1.1
Content-Type
:
application/xml
/orders/333
HTTP
<order
<order id=
"333"
>
<customer
<customer id=
"123"
>
...
</customer>
</customer>
</amount>
<cancelled>true</cancelled>
<order-entries>
...
</order-entries>
</order>
<amount>
<amount>
$99.99
</amount>
But what happens if the order can't be cancelled? We may be at a certain state in our order
process where such an action is not allowed. For example, if the order has already been
shipped, it cannot be cancelled. In this case, there really isn't a good HTTP status code to
send back that represents the problem. A better approach would be to embed a
cancel
link:
<order
<order id=
"333"
>
<customer
<customer id=
"123"
>
...
</customer>
</customer>
<amount>
<amount>
$99.99
</amount>
</amount>
<cancelled>
</cancelled>
<link rel=
"cancel"
href="http://example.com/orders/333/cancelled"/>
<order-entries>
<cancelled>
false
</cancelled>
<order-entries>
...
