2006/5/2, James M Snell <[EMAIL PROTECTED]>:
Ok, the first draft of PaceMediaEntries4 has been posted, incorporating
the feedback from Tim and clarifying the point that media link entries
MUST contain an atom:summary element and that servers may populate
required elements with content derived from the media resource or any
other source.
http://www.intertwingly.net/wiki/pie/PaceMediaEntries4
"""
When the server generates a response with a status code of 201
("Created"), it
MAY also return a response body, which, if provided, MUST be an Atom
Entry Document
representing the newly-created resource. […]
Responses that contain an Atom Entry Document representing the
created resource
SHOULD contain a Content-Location header with the same value as the Location
header.
"""
First, I find those two sentences a bit contradictory or at least
repeat themselves (the response must be an entry representing the
newly-created resource, and responses that contain an entry
*representing the created resource* should etc.)
I also still don't understand why the response body, if provided,
"must" be an Atom Entry Document: hey, clients can look at the
Content-Type to know if it's an Atom Document and read the first few
bytes to discover whether it's an Atom Feed Document or an Atom Entry
Document (eventually, I'd be OK to spec that an application/atom+xml
response body to a POST request for creation *must* be an Atom Entry
Document and *mustn't* be an Atom Feed Document).
Let me try rephrasing:
"""When the server generates a response with a status code of 201
("Created") and provide a response body, clients MUST NOT assume the
response body represents the newly-created resource unless it is an
Atom Entry Document and the response contains a Content-Location
header with the same value as the Location header. When generating
response with a Content-Type of application/atom+xml, the response
body MUST be an Atom Entry Document (i.e. clients can assume it will
not be an Atom Feed Document)."""
— or —
"""When the server generates a response with a status code of 201
("Created"), it MAY also return a response body, which, if provided,
MUST NOT be an Atom Feed Document. Clients MUST NOT assume the
response body represents the newly-created resource unless it is an
Atom Entry Document and the response contains a Content-Location
header with the same value as the Location header."""
It might also be useful either a) paraphrasing RFC2616 saying that
Content-Location might be a relative URL (relative to the request URI)
or b) spec'ing that Content-Location values must be absolute URLs in
the context of the Atom Publishing Protocol.
I'd prefer b), a bit easier to implement for clients, and a noop for
servers (well, except eventually for some cases where they provide a
Content-Location with a value different from the Location value)
"""
8.2 The 'edit' Link
Each member Entry within a collection SHOULD contain an atom:link element with
a link relation of "edit" that contains the IRI used to retrieve, update or
delete the member Entry.
"""
I thought this was changed to a MAY. How about just describing the
"edit" link relation meaning and either leave implicit or explicitly
say that an entry in a collection listing without an [EMAIL PROTECTED]"edit"]
is not editable.
(Note that it's not really clear per the actual wording whether an
entry retrieved through its [EMAIL PROTECTED]"edit"] should in turn also
contain such a link or not)
"""
Deletion of a media link entry SHOULD result in the deletion of the
linked media resource.
"""
Any reason to make it a SHOULD rather than a MUST?
"""
[…] A server may or may not allow a
client to modify the server selected values for these elements.
"""
This is related to the problem above with [EMAIL PROTECTED]"edit"]: if the
server does not allow a client to modify the server selected values,
how does it do?
Could be explained a bit more with something like:
"""A server may or may not allow a client to modify the server
selected values for these elements, for example by not providing an
atom:link with a link relation of "edit" (the entry is not editable
neither deletable), by refusing PUT requests with a status code of 405
("Method Not Supported"), by refusing PUT requests modifying those
field values with a status code of 409 ("Conflict") or by overwriting
any value set by the client."""
"""
10.2 The "edit-resource" Link Relation
The Atom Protocol adds the value "edit-resource" to the Atom Registry
of Link Relations
(see section 7.1 of [RFC4287]). The value of the href attribute is an
IRI that may be used
to modify a media resource associated with an entry.
"""
How about adding something like
"""This specification assigns no significance to atom:link elements
with a link relation of "edit-resource" as direct children of
atom:feed elements, or within entries whose atom:content "type"
attribute value is not a media-type (e.g. the attribute is absent or
its value is one of "text", "html" or "xhtml"): because those contents
have no media-types, they cannot reliably be sent over HTTP outside an
Atom Entry."""
"""
The app:accept
element value specifies a comma-separated listing of media-ranges [RFC2616]
identifying the types of representations that may be POSTed to the
Collection's URI.
"""
Still lacks something about "qvalues" and "accept-parameters" ;-)
maybe also something about prevalence of "wildcard media-ranges" over
"media-type media-ranges", e.g. what does this mean: <accept>image/*,
image/png</accept>
"""
A value of "entry" indicates that Atom Entry Documents can be posted
to the Collection.
"""
I assume it implies that when this value is not present in the list,
the collection doesn't accept Atom Entry Documents?
Given that any collection member has an Atom Entry "representation"
(or call it "description" if you want for "media link entries"), be it
editable or not, then if a server accepts image/png, why couldn't it
also accept an Atom Entry Document with an inlined, based64-encoded
image/png?
I understand that it's meant to represent text/html/xhtml
atom:content/@type values but it's really not clear per this Pace.
"""
If the accept element is omitted, clients SHOULD assume that only Atom
Entry documents
will be accepted by the collection.
"""
See above about the description of an Atom Entry Document
(text/html/xhtml content vs. inlined "media-typed" content)
"""
If present, the value of the accept element MUST NOT
be empty and MUST NOT contain leading or trailing whitespace.
"""
What's the rational behind this constraint? Also, why couldn't
media-ranges not be separated with commas *and some white-space*? Is
the problem about "what is white-space"? I'd answer that "white-space"
could be defined the same as the "S" production of XML 1.0, which also
appears to be almost the same as the "LWS" production of HTTP/1.1
(_almost_ the same, because HTTP uses CRLF end-of-lines and is
line-based so CRLF without a following SP or HT is an "end of field")
Good work James, thank you. Actually, it's becoming so similar to what
I think that I do not have to bother writing an alternative Pace ;-)
--
Thomas Broyer
