Java Reference
In-Depth Information
<
total
>
$199
.
02
</
total
>
<
date
>
December
22
,
2008 06
:
56
</
date
>
...
</
order
>
The service receives the POST message, processes the XML, and creates a new order in the
database using a database-generated unique ID. While this approach works perfectly fine,
we've left our client in a quandary. What if the client wants to edit, update, or cancel the or-
der it just posted? What is the ID of the new order? What URI can we use to interact with the
new resource? To resolve this issue, we will add a bit of information to the HTTP response
message. The client would receive a message something like this:
HTTP
/
1.1 201
Created
Content
-
Type:
application
/
xml
Location: http:
//example.com/orders/233
<
order id
=
"233"
>
<
link rel
=
"self"
href
=
"http://example.com/orders/233"
/>
<
total
>
$199
.
02
</
total
>
<
date
>
December
22
,
2008 06
:
56
</
date
>
...
</
order
>
HTTP requires that if POST creates a new resource, it respond with a code of 201, “Created”
(just like PUT). The
Location
header in the response message provides a URI to the client
so it knows where to further interact with the
Order
that was created (i.e., if the client
wanted to update the
Order
). It is optional whether the server sends the representation of the
newly created
Order
with the response. Here, we send back an XML representation of the
Order
that was just created with the ID attribute set to the one generated by our database as
well as a
link
element.
NOTE
I didn't pull the
Location
header out of thin air. The beauty of this approach is that it is defined
within the HTTP specification. That's an important part of REST—to follow the predefined behavi-
or within the specification of the protocol you are using. Because of this, most systems are self-doc-
umenting, as the distributed interactions are already mostly defined by the HTTP specification.
Updating an Order, Customer, or Product
We will model updating an
Order
,
Customer
, or
Product
using the HTTP PUT method. The
client PUTs a new representation of the object it is updating to the exact URI location that
