[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: draft-gregorio-atompub-multipart-02
On Jul 17, 2008, at 12:44 PM, Joe Gregorio wrote:
http://atompub-mulitpart-spec.googlecode.com/svn/trunk/draft-gregorio-atompub-multipart-02.txt
http://atompub-mulitpart-spec.googlecode.com/svn/trunk/draft-gregorio-atompub-multipart-02.html
http://atompub-mulitpart-spec.googlecode.com/svn/trunk/draft-gregorio-atompub-multipart-02-from-1.diff.html
I have a bunch of editorial comments, but I don't think any of these
affect the protocol. I feel somewhat guilty about coming in late, so
have tried to be as camera-ready as possible, and will cheerfully
whack those that don't pick up objections into the XML myself if Joe
will lend it to me.
Title: Shouldn't it have the word "Resource" in it? "AtomPub
Multipart Media Resource Creation". We're kinda all about resources
here, and "media Creation" is a trifle grammatically awkward
=================
Abstract. s/should/may/ - we're just specifying a way to do this,
we're not asserting that all the servers should or SHOULD go there.
=================
1. Introduction
typo, "representations" is misspelled
Should we add section numbers to some of the RFC5023 references? In
particular to #9.2.
=================
1/2 Design considerations
The draft veers between the past, present, and future tenses. Present
throughout is better. I've tried to catch all these.
1st para s/will be/are/
2nd para s/was/is/g
=================
1.3 Applicability
I apologize in advance for a ton of purely prose-style suggestions; I
can't help it.
s/just creating/the creation of/
==================
2. Terminology
Need to add "foreign markup" from 4287, and perhaps [RFC2387] for
"object root", which was new to me.
=================
3. Multipart Representations
2nd para, 2nd sentence, style rewrite: "There may be other
specifications that define uses for multipart representations in the
AtomPub context; this specification only describes one particular
representation and how to use it in the media-resource creation
process".
I recommend that the 3rd paragraph here be slightly re-written to
define specific terms, "Media Part" and "Entry Part". I'm not sure
the use of "object" in 4. below sits comfortably with RFC2387, which
seems to use "object" for the whole multipart thingie, and there are a
few places later in the draft where the terms are useful. I find that
defined terms are also helpful to implementors when choosing class/
variable names and so on.
A multipart/related POST to a Media Collection MUST be a valid
multipart/related representation as defined by [RFC2387] (Levinson,
E., “The MIME Multipart/Related Content-type,” August 1998.) and MUST
contain two body parts. One, referred to as the Media Part, MUST be an
Atom Entry with a media type of 'application/atom+xml' or 'application/
atom+xml;type=entry'. The other, referred to as the Media Part, MUST
be of a media type acceptable to the collection. The object root MUST
be the Entry Part. The Entry Part's atom:content element MUST have a
'src' attribute whose value is the URI of the related media in the
Media Part. The 'src' attribute value MUST be a 'cid:' URI as defined
by [RFC2392] (Levinson, E., “Content-ID and Message-ID Uniform
Resource Locators,” August 1998.). The Content-Type: header of the
POST request MUST specify "application/atom+xml;type=entry" or
"application/atom+xml".
====================
4. Server Processing
The first sentence is misleading; if it proceeded just like in 5023 we
wouldn't need this! Let me rewrite slightly, using the terms defined
above:
A successful POST of a multipart/related representation to a Media
Collection causes several resource-creation processes to occur as
described in [RFC5023]. The Media Part is used to create a Media
Resource as if it had been posted as a request body to the collection
as described in section 9.6, and the Entry Part is used to create the
corresponding Media Link Entry. Assuming these two steps are
successful, the server returns a 201 status code and a Location:
header pointing to the newly created Media Link Entry. The applicable
rules from [RFC5023] MUST be followed, including Slug: header
processing.
2nd para s/it should either/that is, either/
===================
5. Service Document Extension
XML Pedantry at work here, and single/double quote cleanup:
2nd sentence: The "alternate" attribute's value MUST be one more more
tokens, space-separated if more than one.
4th: The presence of the "multipart-related" token in the "alternate"
attribute's value indicates that the collection accepts multipart/
related POSTs whose Media Part has a content-type matching that
specified in the app:accept element.
2nd-last para: Can we just lose it? Is there any reason to think that
you could suddenly start sending multiparts to random collections?
last para: comma before "loses flexibility"