Java Reference
In-Depth Information
<
order id
=
"233"
>
<
total
>
$199
.
02
</
total
>
<
date
>
December
22
,
2008 06
:
56
</
date
>
<
cancelled
>
true
</
cancelled
>
...
</
order
>
In this example, we PUT a new representation of our order with the cancelled element set to
true. By doing this, we've changed the state of our order from viable to cancelled.
This pattern of modeling an operation as the state of the resource doesn't always fit, though.
What if we expanded on our cancel example by saying that we wanted a way to clean up all
cancelled orders? In other words, we want to purge all cancelled orders from our database.
We can't really model purging the same way we did cancel. While purge does change the
state of our application, it is not in and of itself a state of the application.
To solve this problem, we model this operation as a subresource of
/orders
and we trigger a
purging by doing a POST on that resource. For example:
POST
/
orders
/
purge HTTP
/
1.1
An interesting side effect of this is that because purge is now a URI, we can evolve its inter-
face over time. For example, maybe
GET /orders/purge
returns a document that states the
last time a purge was executed and which orders were deleted. What if we wanted to add
some criteria for purging as well? Form parameters could be passed stating that we only want
to purge orders older than a certain date. In doing this, we're giving ourselves a lot of flexib-
ility as well as honoring the uniform interface contract of REST.
Wrapping Up
So, we've taken an existing object diagram and modeled it as a RESTful distributed service.
We used URIs to represent the endpoints in our system. These endpoints are called resources.
For each resource, we defined which HTTP methods each resource will allow and how those
individual HTTP methods behave. Finally, we defined the data format that our clients and
services will use to exchange information. The next step is to actually implement these ser-
vices in Java. This will be the main topic for the rest of this topic.
[
2
]
I actually borrowed the
link
element from the Atom format. Atom is a syndication format that is
used to aggregate and publish blogs and news feeds. You can find out more about Atom at
ht-
