Subject: I-D ACTION:draft-ietf-atompub-protocol-09.txt

From: [email-masked]
Date: Thu, 29 Jun 2006 02:50:02 -0400

A New Internet-Draft is available from the on-line Internet-Drafts directories.
This draft is a work item of the Atom Publishing Format and Protocol Working Group of the IETF.

	Title		: The Atom Publishing Protocol
	Author(s)	: B. de Hora, J. Gregorio
	Filename	: draft-ietf-atompub-protocol-09.txt
	Pages		: 41
	Date		: 2006-6-28
	
The Atom Publishing Protocol (APP) is an application-level protocol
   for publishing and editing Web resources.  The protocol is based on
   HTTP transport of Atom-formatted representations.  The Atom format is
   documented in the Atom Syndication Format (RFC4287).

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-ietf-atompub-protocol-09.txt

To remove yourself from the I-D Announcement list, send a message to 
[email-masked] with the word unsubscribe in the body of the message.  
You can also visit https://www1.ietf.org/mailman/listinfo/I-D-announce 
to change your subscription settings.

Internet-Drafts are also available by anonymous FTP. Login with the username
"anonymous" and a password of your e-mail address. After logging in,
type "cd internet-drafts" and then
	"get draft-ietf-atompub-protocol-09.txt".

A list of Internet-Drafts directories can be found in
http://www.ietf.org/shadow.html 
or ftp://ftp.ietf.org/ietf/1shadow-sites.txt

Internet-Drafts can also be obtained by e-mail.

Send a message to:
	[email-masked].
In the body type:
	"FILE /internet-drafts/draft-ietf-atompub-protocol-09.txt".
	
NOTE:	The mail server at ietf.org can return the document in
	MIME-encoded form by using the "mpack" utility.  To use this
	feature, insert the command "ENCODING mime" before the "FILE"
	command.  To decode the response(s), you will need "munpack" or
	a MIME-compliant mail reader.  Different MIME-compliant mail readers
	exhibit different behavior, especially when dealing with
	"multipart" MIME messages (i.e. documents which have been split
	up into multiple messages), so check your local documentation on
	how to manipulate these messages.

Below is the data which will enable a MIME compliant mail reader
implementation to automatically retrieve the ASCII version of the
Internet-Draft.

---

From: "Sylvain Hellegouarch" <[email-masked]>
Date: Thu, 29 Jun 2006 10:49:40 +0100 (BST)

James,

>
> First minor nit:
>
> Section 8.1:
>
>    When the POST request contains an Atom Entry Document, ...
>
> that should read "POST response" and not "POST request"

I think you make a mistake. POST request is the correct wording here...
well it is my understanding.

But if you are correct one should read, "a response to a POST request" not
"POST response".

- Sylvain

---

From: James M Snell <[email-masked]>
Date: Thu, 29 Jun 2006 02:35:31 -0700

First minor nit:

Section 8.1:

- James

---

From: James M Snell <[email-masked]>
Date: Thu, 29 Jun 2006 02:41:14 -0700

I note that the examples in the spec were likely cut-n-pasted from the
wiki, for instance:

       Content- Length: nnn
       Content- Type: application/atom+xml; charset="utf-8"
       Content- Location: http://example.org/edit/first-post.atom

The space following the "Content-" is intended to get around a wiki bug
and should be removed from the samples in the spec.

- James

---

From: James M Snell <[email-masked]>
Date: Thu, 29 Jun 2006 02:54:44 -0700

Ok, reading it again I think you're right, either way, however, the
construction of the sentence looks odd. Shortening it up to use your
wording below would likely be better:

   The response to a POST request containing an Atom Entry Document
   SHOULD contain a Content-Location header that contains the same
   character-by-character value as the Location header.

- James

---

From: Bill de hÓra <[email-masked]>
Date: Thu, 29 Jun 2006 12:24:59 +0100

Hi James,

I understand what you mean. We'll patch the English on that sentence 
next time around.

cheers
Bill

---

From: Bill de hÓra <[email-masked]>
Date: Thu, 29 Jun 2006 12:25:58 +0100

So much for my search/replace skillz. Ok, will fix.

cheers
Bill

---

From: Andreas Sewe <[email-masked]>
Date: Thu, 29 Jun 2006 15:52:56 +0200

Well, the subject says it all; here they are:

- It were nice if the example in 7.1 would include @xml:lang, since both 
  workspace/@title and collection/@title are Language-Sensitive. 
Granted, there might be a Content-Language response header (not shown) 
to do the job, but IMHO the example would benefit from making language 
information explicit.

- The proposed file extension for APP Introspection Documents (.atomsrv) 
and its media type (application/atomserv+xml) are inconsistent. It would 
IMHO be better to use either "atomsrv" or "atomserv" consistently in 
both file extension and media type. Everything else is just confusing 
for no good reason.

Regards,

Andreas Sewe

FWIW, I have set the Reply-To to atom-protocol, since it seems to be the 
more appropriate list to discuss these things -- not that it really 
matters, given the overlap between atom-syntax's and atom-protocol's 
audiences...

---

From: Bill de hÓra <[email-masked]>
Date: Thu, 29 Jun 2006 16:34:53 +0100

Andreas Sewe wrote:
>  workspace/@title and collection/@title are Language-Sensitive. Granted, 
> there might be a Content-Language response header (not shown) to do the 
> job, but IMHO the example would benefit from making language information 
> explicit.

+1.

Which are clients supposed to respect in a conflict, the 
Content-Language header or the xml:lang, ie, does XML On The Web Failing 
  Miserably, Utterly, And Completely extend to Content-Language+xml:lang?

> both file extension and media type. Everything else is just confusing 

I have no strong prefs here (other than liking "application/app+xml").

cheers
Bill

---

From: Eric Scheid <[email-masked]>
Date: Fri, 30 Jun 2006 02:00:23 +1000

> Miserably, Utterly, And Completely extend to Content-Language+xml:lang?

xml:lang, if you think of xml being nested.

in other words, what is the lang of the atom:content below:

    HTTP 200 OK
    Content-Language: ch
    ...

    <feed xml:lang="fr" ...>
        <entry xml:lang="it">
            <content xml:lang="en" ...>
                ...
            </content>
            ...
        </entry>
        ...
    </feed>

e.

---

From: Bill de hÓra <[email-masked]>
Date: Thu, 29 Jun 2006 17:52:36 +0100

>             <content xml:lang="en" ...>

Hi Eric,

I guess my next question is - do we need to tell people this in the 
protocol spec, or should I Just Know That, Utterly, And Completely ?

cheers
Bill

---

From: James M Snell <[email-masked]>
Date: Thu, 29 Jun 2006 19:43:58 -0700

A few more comments:

Section 4:

   Note that when an IRI is used for resource retrieval over HTTP, the
   IRI is first converted to a URI according the procedure defined in
   [RFC3987] section 3.1.  The resource that the IRI locates is the same
   as the one located by the URI obtained after converting the IRI.

IRI to URI conversion is mentioned at least twice in the spec. It would
probably be a good idea to eliminate the duplicates

Also, the protocol indicates that POST is used for creation of
resources, however, POST is only defined on the Collection URI.  There
has been  discussion about and there is an example of (gdata) using the
POST method on Member resource edit URI's for purposes other than
creation of resources. Perhaps it would make sense to include a note
that the behavior of the POST operation on any URI other than the
Collection URI is undefined.

Section 5.3.2

   1.  The client PUTs an updated representation to the Member's URI.

This should probably be "The client PUTs an updated representation to
the Member's edit URI" given that there is a distinction between the
Location URI and the edit URI as specified by the edit via (e.g. the
gdata api).

Also,

   2.  Upon a successful update of the resource the server responds with
       a status code of 200.

Would not a 204 No Content be appropriate as well given that we're not
requiring or recommending the update to return a response?

Also, should we recommend that a PUT response contain the entry just
like with POST requests?

Section 5.3.3

   1.  The client sends a DELETE request to the Member's URI.

Same as section 5.3.2 above.  "The client sends a DELETE request to the
Member's edit URI"

   2.  Upon the successful deletion of the resource the server responds
       with a status code of 200.

Same as section 5.3.2 above, a 204 No Content would also be appropriate
and is likely desirable in this case given that there is no response entity.

Section 7.2.2

   appCollection+ should be appCollection*

Section 7.2.4

   media-type = xsd:string { pattern = "entry,(.+/.+,?)*" }
   entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" }

Aren't these patterns backwards? e.g. the media-type pattern belongs to
entry-or-media-type.

Section 8.2

   In particular, the publishing system in this example filled in some
   values not provided in the original POST.  For example, presumably it
   ascertained the author's name via the authentication protocol used to
   establish the right to post.

Using the author's name in this example is odd given that the name *is*
provided in the original post.  Perhaps if the email address of the
author were filled in on the created entry it would make more sense.

Section 9

   The entries in the returned Atom Feed MUST be ordered by their "atom:
   updated" property, with the most recently updated entries coming
   first in the document order.  Clients SHOULD be constructed in
   consideration of the fact that changes which do not alter the entry's
   atom:updated value will not affect the position of the entry in a
   collection.

If the client PUTs an atom:entry with an changed atom:updated, is the
server required to honor it?