[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
More comments on pre-draft (as of 2007-05-17)
INTRODUCTION, para. 14:
OLD:
The Atom Publishing Protocol (APP) is an application-level protocol
for publishing and editing Web resources. The protocol is based on
HTTP transfer of Atom-formatted representations. The Atom format is
documented in the Atom Syndication Format [RFC4287].
NEW:
The Atom Publishing Protocol (APP) is an application-level protocol
for publishing and editing Web resources. The protocol is based on
HTTP transfer of Atom-formatted representations. The Atom format is
documented in the Atom Syndication Format.
JRE: no references in the abstract, please.
Section 3., para. 3:
OLD:
o IRI - An Internationalized Resource Identifier as defined in
[RFC3987]. Before an IRI found in a document is used by HTTP, the
IRI is first converted to a URI. See Section 4.1.
NEW:
o IRI - An Internationalized Resource Identifier as defined in
[RFC3987]. Before an IRI found in a document can used in an HTTP
request, it must first converted to a URI. See Section 4.1.
JRE: "used by HTTP" doesn't sound right.
Section 3., para. 4:
OLD:
o Resource - A network-accessible data object or service identified
by an IRI, as defined in [RFC2616]. See
[W3C.REC-webarch-20041215] for further discussion on Resources.
NEW:
o Resource - A network-accessible data object or service identified
by an URI, as defined in [RFC2616]. See
[W3C.REC-webarch-20041215] for further discussion on Resources.
JRE: RFC2616 defines resources being defined by HTTL URL (URI).
Section 3., para. 5:
OLD:
o relation (or "relation of") - Refers to the "rel" attribute value
of an atom:link element.
NEW:
o relation (or "relation of") - Refers to the "rel" attribute value
of an atom:link element (see [RFC4287], Section 4.2.7).
JRE: be more specific when referencing other docs (that applies to many
other places as well...).
Section 4.1., para. 1:
OLD:
Atom Protocol documents allow the use of IRIs [RFC3987], as well as
URIs [RFC3986] to identify Resources. Before an IRI in a document is
used by HTTP, the IRI is first converted to a URI according to the
procedure defined in Section 3.1 of [RFC3987]. In accordance with
that specification, the conversion SHOULD be applied as late as
possible. Conversion does not imply Resource creation - the IRI and
the URI into which it is converted identify the same Resource.
NEW:
Atom Protocol documents allow the use of IRIs [RFC3987], as well as
URIs [RFC3986] to identify Resources. Before an IRI in a document is
used in HTTP requests, the IRI is first converted to a URI according
to the
procedure defined in Section 3.1 of [RFC3987]. In accordance with
that specification, the conversion SHOULD be applied as late as
possible. Conversion does not imply Resource creation - the IRI and
the URI into which it is converted identify the same Resource.
JRE: see above.
Section 5.3., para. 3:
OLD:
2. If the Member Resource was created successfully, the server
responds with a status code of 201 and a Location: header that
contains the IRI of the newly created Entry Resource. Media
Resources could have also been created and their IRIs can be
found through the Entry Resource. See Section 9.6 for more
details.
NEW:
2. If the Member Resource was created successfully, the server
responds with a status code of 201 and a Location: header that
contains the URI of the newly created Entry Resource. Media
Resources could have also been created and their IRIs can be
found through the Entry Resource. See Section 9.6 for more
details.
JRE: IRI->URI
Section 5.4.2., para. 3:
OLD:
2. If the deletion is successful the server responds with a status
code of 200.
JRE: are we sufficiently clear that this may be another 2xx status, such
as 204, as well?
Section 8.3.4., para. 2:
OLD:
The app:accept element is similar to the HTTP Accept request-header
[RFC2616]. Media type parameters are allowed within app:accept, but
app:accept has no notion of preference - "accept-params" or "q"
arguments, as specified in Section 14.1 of [RFC2616] are not
significant.
NEW:
The app:accept element is similar to the HTTP Accept request-header
[RFC2616]. Media type parameters are allowed within app:accept, but
app:accept has no notion of preference - "accept-params" or "q"
arguments, as specified in Section 14.1 of [RFC2616] are not
significant.
JRE: it's now less similar to the Accept header than it used to. Maybe
we need to rephrase this.
Section 9.1., para. 2:
OLD:
Member URIs appear in two places. They are returned in a Location
header after successful Resource creation using POST, as described in
Section 9.2 below. They can also appear in a Collection Feed's
entries, as atom:link elements with a link relation of "edit".
NEW:
Member URIs appear in two places. They are returned in a Location
header after successful Resource creation using POST, as described in
Section 9.2 below. They can also appear in a Collection Feed's
entries, as atom:link elements with a link relation of "edit".
JRE: in atom:link, do we see URIs or IRIs?
Section 9.1., para. 3:
OLD:
A Member Entry SHOULD contain such an atom:link element with a link
relation of "edit", which indicates the Member URI.
NEW:
A Member Entry SHOULD contain such an atom:link element with a link
relation of "edit", which indicates the Member URI.
JRE: see above.
Section 9.5.1., para. 5:
OLD:
The server signals a successful creation with a status code of 201,
and returns an ETag header in the response. Because in this case the
server returned a Content-Location and Location header with the same
value, the returned Entry representation can be understood to be
complete (see Section 9.2) and thus the ETag entity value can be also
be used.
NEW:
The server signals a successful creation with a status code of 201,
and returns an ETag header in the response. Because in this case the
server returned a Content-Location and Location header with the same
value, the returned Entry representation can be understood to be
complete (see Section 9.2) and thus the ETag entity value can be also
be used for subsequent operations.
Section 9.5.1., para. 16:
OLD:
The server however has since received a more recent copy than the
client's, and responds with a status code of 412 (Precondition
Failed).
HTTP/1.1 412 Precondition Failed
Date: Sat, 24 Feb 2007 16:34:11 GMT
NEW:
The server however has since received a more recent copy than the
client's, and responds with a status code of 412 (Precondition
Failed).
HTTP/1.1 412 Precondition Failed
Date: Sat, 24 Feb 2007 16:34:11 GMT
JRE: whitespace. Also: shouldn't that contain a response body?
Section 9.6.1., para. 13:
OLD:
HTTP/1.1 200 Ok
Date: Fri, 8 Oct 2006 17:17:11 GMT
Content-Length: nnn
NEW:
HTTP/1.1 200 Ok
Date: Fri, 8 Oct 2006 17:17:11 GMT
Section 9.7.2., para. 4:
OLD:
See Section 9.2.1 for an example of the Slug: header applied to the
creation of an Entry Resource.
JRE: can we please spell out what the example slug stands for?
Section 10.1., para. 1:
OLD:
Collections can contain large numbers of Resources. A client such as
a web spider or web browser might be overwhelmed if the response to a
GET contained every Entry in a Collection - in turn the server might
also waste bandwidth and processing time on generating a response
that cannot be handled. For this reason, servers MAY respond to
Collection GET requests with a Feed Document containing a partial
list of the Collection's members, and a link to the next partial list
feed, if it exists. The first such partial list returned MUST
contain the most recently edited member Resources and MUST have an
atom:link with a "next" relation whose "href" value is the URI of the
next partial list of the Collection. This next partial list will
contain the next most recently edited set of Member Resources (and an
atom:link to the following partial list if it exists).
NEW:
Collections can contain large numbers of Resources. A client such as
a web spider or web browser might be overwhelmed if the response to a
GET contained every Entry in a Collection - in turn the server might
also waste bandwidth and processing time on generating a response
that cannot be handled. For this reason, servers MAY respond to
Collection GET requests with a Feed Document containing a partial
list of the Collection's members, and a link to the next partial list
feed, if it exists. The first such partial list returned MUST
contain the most recently edited member Resources and MUST have an
atom:link with a "next" relation whose "href" value is the IRI of the
next partial list of the Collection. This next partial list will
contain the next most recently edited set of Member Resources (and an
atom:link to the following partial list if it exists).
JRE: URI->IRI.
Section 10.2., para. 1:
OLD:
The "app:edited" element is a Date construct as defined by [RFC4287]
whose content indicates the last time an Entry was edited. If the
entry has not been edited yet, the content indicates the time it was
created. Atom Entry elements in Collection documents SHOULD contain
one "app:edited" element, and MUST NOT contain more than one.
NEW:
The "app:edited" element is a Date construct as defined by [RFC4287,
Section 3.3]
whose content indicates the last time an Entry was edited. If the
entry has not been edited yet, the content indicates the time it was
created. Atom Entry elements in Collection documents SHOULD contain
one "app:edited" element, and MUST NOT contain more than one.
Section 12.1., para. 1:
OLD:
This document defines a new "type" parameter for use with the
"application/atom+xml" media type:
JRE: say that this uses a RFC4234-style ABNF.
Section 15.7., para. 3:
OLD:
Additional information about XHTML and HTML content safety can be
found in Section 8.1 of [RFC4287]
JRE: didn't we discuss at some point of time what we need to warn
against the "million laughs attack"? Can't see anything here....
Section 16.1., para. 11:
JRE: I think most notes to the RFC Editor can go if we just always say
"This Specification", and insert the IESG as change controller.
Best regards, Julian