This is the Title of the Book, eMatter Edition
Copyright © 2007 O’Reilly & Associates, Inc. All rights reserved.
• POST the purchase order to that resource and get back a URI for the order (when
• Send a
GET request asking for an order number, then PUT the order there.
Two disadvantages of using the POST method
POST has a reliability problem if a client loses its contact with the server after POSTing
a purchase order. The order might have been accepted, and the reply was lost, but
then again the order might have been lost and should be resent. There’s no way for
the client to know what happened.
POST can also be confusing here; a client could
use POST to submit an initial order, but then PUT to update it.
Two disadvantages of the GET and PUT combination
The first disadvantage of using the GET method is that the /orders/ resource is
already taken. The system may want it to do something different, for instance to
return a list of orders for particular customer. Because of this, a different resource
(for example, /orders/new) is needed that will respond to
GET requests and return a
URL in which the order can be submitted (the only real disadvantage is that two
roundtrips are required). The second disadvantage is that now the server has a
potential race condition to address (if it doesn’t keep the generated order numbers
on the server side, it can generate the same order number for more than one cus-
tomer), and the
PUT request has to be smart enough to deal with that.
Choosing the implementation
Because the reliability problem seems to be the more interesting issue to address, the
example will implement the
GET and PUT combination.
For now, the actual XML
documents for purchase orders will be skipped over (you can design these as an exer-
cise), and the text will describe the interactions only to highlight the important
First, a client receives the information about the resource where the URL and num-
ber for a new order can be obtained (
/books/progwebsoap/orders/new in this exam-
ple). This information may be included as part of the book list (the /books/
representation), or it may be published somewhere.
Following this, the client sends a
GET request to the URL and receives back a new
URL where the order should be submitted.
Here’s the request:
* Though the network may go down during the PUT request, it is safe for a client to resubmit the message when
in doubt, because an order with the same number will be treated as the same order, whereas resending the
order with the POST message may result in duplicate orders.