Java Reference
In-Depth Information
clean from our databases, cancelling only changes the state of the
Order
and retains it within
the system. How should we model such an operation?
Overloading the meaning of DELETE
Cancelling an
Order
is very similar to removing it. Since we are already modeling remove
with the HTTP DELETE method, one thing we could do is add an extra query parameter to
the request:
DELETE
/
orders
/
233
?
cancel
=
true
true
Here, the
cancel
query parameter would tell our service that we don't really want to remove
the
Order
, but cancel it. In other words, we are overloading the meaning of DELETE.
While I'm not going to tell you not to do this, I will tell you that you shouldn't do it. It is not
good RESTful design. In this case, you are changing the meaning of the uniform interface.
Using a query parameter in this way is actually creating a mini-RPC mechanism. HTTP spe-
cifically states that DELETE is used to delete a resource from the server, not cancel it.
States versus operations
When modeling a RESTful interface for the operations of your object model, you should ask
yourself a simple question: is the operation a state of the resource? If you answer yes to this
question, the operation should be modeled within the data format.
Cancelling an
Order
is a perfect example of this. The key with cancelling is that it is a spe-
cific state of an
Order
. When a client follows a particular URI that links to a specific
Order
,
the client will want to know whether the
Order
was cancelled or not. Information about the
cancellation needs to be in the data format of the
Order
. So let's add a cancelled element to
our
Order
data format:
<order
<order id=
"233"
>
<link
<link rel=
"self"
href=
"http://example.com/orders/233"
//>
<total>
<total>
$199.02
</total>
</total>
<date>
<date>
December 22, 2008 06:56
</date>
</date>
<cancelled>
false
</cancelled>
...
</order>
</order>
Since the state of being cancelled is modeled in the data format, we can now use our already
defined mechanism of updating an
Order
to model the cancel operation. For example, we
could PUT this message to our service:
PUT
/
orders
/
233
HTTP
/
1.1
Content
-
Type:
application
/
xml
