2006/5/24, Tim Bray <[EMAIL PROTECTED]>:
<co-chair-mode>
As we see it, there are really only 1.5 issues outstanding. Media
entries is obvious. I had an action item to make PaceMediaEntries
more human-readable; thus, check out http://www.intertwingly.net/wiki/
pie/PaceMediaEntries5
There's been a lot of discussion of the iterations of this Pace, and
a lot of it was of the form "sort of OK, but I'm uncomfortable with
XXX". So before we do the last-chance +/- survey, we'd like one
last call for amendments, improvements to the Pace that might move
people from negative to positive.
I'm -1 to the following two paragraphs:
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 and SHOULD perform a GET on the member resource before editing.
Any response to the POST request that contains an Atom Entry Document
representing the created resource SHOULD contain a Content- Location header
with the same character-by-character value as the Location header.
First, there's no reason for the MUST in "MUST be an Atom Entry
Document representing the newly-created resource"; I'm still
uncomfortable with the second paragraph, and I see no reason for the
SHOULD in "SHOULD also return a response body".
I propose something in the line of the following:
When the server generates a response with a status code of 201 (Created),
it MAY also return a response body. In such a case, clients MUST NOT assume
it represents the newly-created resource unless there is Content-Location
header with the same character-by-character value as the Location header.
Clients MUST NOT assume that an Atom Entry returned is a full
representation of
the member resource and SHOULD perform a GET on the member resource
before editing.
Returning an Atom Entry representing the newly-created resource as the body
of a 201 (Created) response is a mean to communicate some minimal information
about the newly-created resource (among which the title, author and "atom:id")
and can then prevent clients from performing a GET on the member resource
immediately after the POST.
I'm not kind of my second paragraph but the meaning is: there's no
need for a SHOULD for servers to return a response body, but
implementors might want ot do it for the following reason (i.e. help
clients and prevent them from issuing a GET immediately after the
POST). In other words, it describes the POST response body with
Location=Content-Location as an optimization trick, no more no less
(clients don't need to issue a GET, so servers won't need to respond
ot it; saves bandwidth and server work).
The following paragraph could be added just after the
Content-Location=Location sentence as a justification (because it's
always useful to know why a constraint exists):
Note that this is a small variation from HTTP/1.1, where the Content-Location
header value can be a relative URI, hence which doesn't enforce a
character-by-character equality. This added constraint is intended to improve
interoperability, because HTTP/1.1 doesn't define the base-URI in
POST responses,
with which to resolve a relative URI.
The last paragraph of section 8.2 should be moved to section 8.1: it's
not part of the example.
Section 8.3 (the "edit" link relation): is the SHOULD applying to
entries in a "collection feed" only? or also to Atom Entry Documents
retrieved using the "collection feed entry's rel='edit' link"?
Also, I'd like to hear from Google about this, especially wrt
optimistic concurrency. For example, what does dereferencing a
rel="edit" link's href returns? is it always the latest
representation? does it result in a redirect to the latest "edit URI"?
is the rel="edit" in an Atom Entry Document only used for PUT and
DELETE? If so, couldn't we just use rel="self" in the "collection
feed" (if an entry is not retrievable outside a feed, there are good
chances it is not editable), and define rel="edit" only for updates
and deletion (and not to retrieve the entry) and thus as a SHOULD in
the Atom Entry Document only.
Section 8.4, the second paragraph says there *are* two resources,
while you were saying the spec should not go for one or another.
Also, if you can't POST an Atom Feed (or at least, POSTing an Atom
Feed is not defined as a request to create a new resource as
represented by the feed), why not simply using a link with rel="edit"
and a "type" attribute (different from application/atom+xml) instead
of a new rel="edit-media"? So <link rel="edit"
type="application/atom+xml" href="..."> is used to edit the "media
link entry" and <link rel="edit" type="..." href="..."> is used to
edit the "media resource".
Section 7.2.4 (the "app:accept" element): there's no need for the
special value "entry", as we don't define POSTing an Atom Feed
Document (see comments above about section 8.4). An extension defining
such a thing will just need an extension element in the
introspection/service document (instead of a special value "feed", for
example). Accepting representations of a media type doesn't mean you
will accept all of them, so you'll be right refusing Atom Feed
Documents even if you have
<app:accept>application/atom+xml</app:accept> in the
introspection/service document.
I've no opinion yet on categories handling... Having it as an
extension wouldn't bother me...
--
Thomas Broyer
