>
Hi Jerome,
I'd like to come back to a point we discussed last week. I mentioned that I
wanted to return a representation of a resource that was created by a POST.
You wrote:
> Hmm, let's got back to the POST definition:
>
> "If a resource has been created on the origin server, the response SHOULD be
> 201 (Created) and contain an entity which describes the status of the
> request and refers to the new resource, and a Location header (see section
> 14.30)."
>
> Notice that your response entity should "describe" the status rather than
> just return a representation of the created resource. The client should then
> GET the created resource at the URI indicated by your Response.redirectRef
> property.
>
> So, it seems that the handleGet() is not necessary here. If you still want
> to return a negotiated resource representation as a status description page,
> you should then call handleGet() before setting the status to CREATED
> otherwise it will be overridden.
>
Consider this section of the Atom Publishing Protocol:
"8.1 Creating resources with POST
To add members to a collection, clients send POST requests to the collection's
URI. Collections MAY impose constraints on the media-types of request entities
POSTed to the collection and MAY generate a response with a status code of 415
("Unsupported Media Type").
If an entry was created in the collection which received the POST, its URI MUST
be returned in an HTTP Location header.
When the server generates a response with a status code of 201 ("Created"), it
SHOULD also return a response body, which, if provided, MUST be an Atom Entry
Document representing the newly-created resource. Clients MUST NOT assume that
an Atom Entry returned is a full representation of the member resource.
Since the server is free to alter the posted entry, for example by changing the
content of the "id" element. returning the entry as described in the previous
paragraph can be useful to the client, enabling it to correlate the client and
server views of the new entry."
This is a good example of why 1) you'd want to create a resource with POST
and 2) why you'd want to return a representation (not just a state) in the
response.
Getting the representation back saves a round trip to the server in cases where
the client needs to cache the newly created resource (the server might have set
server-related properties like created-by, state, id, etc.).
On a related note: for the type of application I write, I never use PUT to
create resources because I never know ahead of time where the resource will
end up.
It is my understanding that you PUT a resource when you know the URI it should
be put at (e.g. you PUT a picture at http://me.com/album/winter2007/bob.jpg);
in my case, the resource I create are stored in the DB, and their URI contains
the row #. For instance: http://company.com/account/123. Therefore, to create
a foo resource I POST to the foos resource (http://company.com/foos) and
return a description of the newly created foo in the response's body (as
well as the URI in the Location header).
For some resources it's a little bit more complex:
- I create a create.account transaction by POSTing to the
/transactions/createAccount resource
- I get a transaction URI back (in the Location header)
- I POST to that transaction resource, with a description of the account
resource I want to create in the request body
- the server returns a 201 status code with the URI of the newly created
account resource in the Location header, and a description of the account in
the response body.
If I want to modify this account:
- I create a transaction by POSTing to the /transactions/editAccount resource
- The server creates a /transaction/editAccount/456 resource
- I POST my modifications to this resource
- I get back a 200 and the representation of the modified account in the
response body.
This makes my POSTs idempotent (I check that the tx hasn't been already
executed before processing the request), and solves the double-post problem.
I might later have the client DELETE the transaction to notify the server that
it (the client) has received the acknowledgment.
-Vincent.
