[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