Subject: PacePostLocationMust created

From: Joe Gregorio <[email-masked]>
Date: Tue, 20 Jul 2004 23:41:54 -0400

http://intertwingly.net/wiki/pie/PacePostLocationMust

Hopefully a simple Pace to tighten up some 
of the language on responses from a POST
to a PostURI in the Publishing Protocol.

------------------------------------------------------------
Abstract
======

Require that the response from POST to a PostURI MUST contain a
location header. Also specify which contraints apply to the response
body.

Status
=====

Open

Rationale
=======

Clears up vagueness in the current wording and makes client editing
easier by reducing the number of round trips.

Proposal
=======

Change 3.1.3.1 to read:

The Response MUST include a Location: header with the URI of the
created resource. The URI returned must be the EditURI of the entry
just created. The body of the response SHOULD contain the newly
created entry. If the entry is present in the response body then it
MUST conform to the same constraints listed for responses to a GET on
an EditURI. User agents MUST NOT depend on the server returning a
response body. If the server does return a response body then the user
agents MUST NOT depend on the response body having a content-type of
'application/atom+xml". Note that the server may chose to omit the
content in the response, particularly if it is large.

A 201 response MAY contain an ETag response header field indicating
the current value of the entity tag for the requested variant just
created.

If the entry returned is subsequently changed the user agent can
update the entry by submitting it via PUT to the EditURI. If an ETag
was returned with the creation of the entry then the user agent SHOULD
include an If-Match header in the request that contains that ETag.

Impacts
======

Allows clients to depend upon getting the URI of the EditURI in the
response header thus avoiding a round trip to the FeedURI just to get
the EditURI of a newly created entry.

Notes
====

Note that the entry returned fits the requirements in RFC 2616 for a
201 response since it contains a link element to the HTML version of
the newly created entry. From RFC 2616:

      The response SHOULD include an entity containing a list of
resource  characteristics and location(s) from which the user or user
agent can choose the one most appropriate. The entity format is
specified by the media type given in the Content-Type header field.

------------------------------------------------------------

    Thanks,
    -joe

-- 
Joe Gregorio        http://bitworking.org