Abstract
One final rev on PaceMediaEntries3
Status
Proposed
Rationale
The WG seems to be in agreement that the current definition of Media Collections is sub-optimal. There is inconsistency in the behaviors of media and entry collections, there is ambiguity in what the Location header needs to point at, there are problems when trying to match up what a client posted to what actually shows up in the collections Atom feed, etc. This Pace attempts to fix all of those issues by redefining the problem.
Proposal
8. Collections
8.1 Creating resources with POST
To add members to a collection, clients send POST requests to the collection's
URI. Collections MAY impose constraints on the media-types of request entities
POSTed to the collection and MAY generate a response with a status code of
415 ("Unsupported Media Type"). On successful creation, the response to the
POST request MUST return a Location: header with the URI of an Atom Entry
Document representing the newly created resource.
When the server generates a response with a status code of 201 ("Created"), it
SHOULD also return a response body, which, if provided, MUST be an Atom Entry Document
representing the newly-created resource. Clients MUST NOT assume that an Atom Entry
returned is a full representation of the member resource and SHOULD perform a GET on
the member resource before editing.
Any response to the POST request that contains an Atom Entry Document representing
the created resource SHOULD contain a Content-Location header with the same
character-by-character value as the Location header.
Clients MUST NOT assume that the URI provided by the Location: header can be
used to edit the created entry.
8.1.1 Example
Below, the client sends a POST request containing an Atom Entry to the URI
of the Collection:
POST /myblog/entries HTTP/1.1
Host: example.org
User- Agent: Thingio/1.0
Content- Type: application/atom+xml
Content- Length: nnn
<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2003-12-13T18:30:02Z</updated>
<author><name>John Doe</name></author>
<content>Some text.</content>
</entry>
The server signals a successful creation with a status code of 201. The
response includes a "Location" header indicating the URI of the Atom
Entry and a representation of that Entry in the body of the response.
HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content- Length: nnn
Content- Type: application/atom+xml; charset="utf-8"
Content- Location: http://example.org/edit/first-post.atom
Location: http://example.org/edit/first-post.atom
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2003-12-13T18:30:02Z</updated>
<author><name>John Doe</name></author>
<content>Some text.</content>
<link rel="edit" href="http://example.org/edit/first-post.atom" />
</entry>
Note that the Entry created by the server may or may not exactly match the
Entry POSTed by the client. In particular, a server MAY change the values
of various elements in the Entry such as the atom:id, atom:updated and
atom:author values and MAY choose to remove or add metadata elements.
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.
8.3 Media resources and media link entries
An entry which links to a resource using the "src" attribute of the atom:content
element is referred to as a "media link entry", and the target of the "src" attribute
as a "media resource". A media resource is typically non-textual and a media link entry
is typically used to provide metadata about it. Such an entry SHOULD contain an atom:link
element with a link relation of "edit-media" that contains the IRI used to modify the
media resource. Deletion of a media link entry SHOULD result in the deletion of the
linked media resource.
To add an entry with an associated media resource to a collection, clients send a
POST request containing a representation of the media resource to the collection's
URI.
Implementors should note that, per the requirements of [RFC4287], media link entries
MUST contain an atom:summary element. Upon successful creation of a media link entry,
a server MAY choose to populate the atom:summary element (as well as other required
elements such as atom:id, atom:author and atom:title) with content derived from the
POSTed media resource or from any other source. A server may or may not allow a
client to modify the server selected values for these elements.
8.3.1 Title: Header
A POST to a Collection requesting the creation of an entry with an associated media
resource SHOULD contain a Title: header indicating the client's suggested title for
the resource.
POST /myblog/fotes HTTP/1.1
Host: example.org
Content- Type: image/png
Content- Length: nnnn
Title: An Atom-Powered Robot
...binary data...
The server MAY use the content of the Title: header, as provided or in a modified form,
in constructing a title for the resource.
Title = "Title" ":" [TEXT]
The syntax of this header MUST conform to the augmented BNF grammar in section 2.1 of
the HTTP/1.1 specification [RFC2616]. The [TEXT] rule is described in section 2.2 of
the same document. Words of *TEXT MAY contain characters from character sets other
than [ISO88591] only when encoded according to the rules of [RFC2047].
8.3.2 Example
Below, the client sends a POST request containing a PNG image resouce to the
URI of the Collection:
POST /myblog/entries HTTP/1.1
Host: example.org
Content- Type: image/png
Content- Length: nnn
Title: A picture of the beach
{binary data}
The server signals a successful creation with a status code of 201. The
response includes a "Location" header indicating the URI of the media link
entry and a representation of that Entry in the body of the response. The
media link entry includes a content element with a src attribute referencing
the media resource, and a link using the link relation "edit-media"
specifying the IRI to be used for modifying the media resource.
HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content- Length: nnn
Content- Type: application/atom+xml; charset="utf-8"
Content- Location: http://example.org/edit/first-post.atom
Location: http://example.org/edit/first-post.atom
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>A picture of the beach</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2003-12-13T18:30:02Z</updated>
<author><name>John Doe</name></author>
<summary type="text" />
<content type="image/png" src="http://example.org/media/img123.png"/>
<link rel="edit" href="http://example.org/edit/first-post.atom" />
<link rel="edit-media" href="http://example.org/edit/img123.png" />
</entry>
Section 9: Change:
Each entry in the Feed Document MUST have an atom:link element with a relation of "edit"
To
Each entry in the Feed Document SHOULD have an atom:link element with a relation of "edit"
Modify Section 10.1
10.1 The "edit" Link Relation The Atom Protocol adds the value "edit" to the Atom Registry of Link Relations (see section 7.1 of [RFC4287]). The value of "edit" specifies that the value of the href attribute is the IRI of an editable Atom Entry Document. When appearing within an atom:entry, the href IRI may be used to update and delete the resource represented by that entry.
Add Section 10.2
10.2 The "edit-media" Link Relation The Atom Protocol adds the value "edit-media" to the Atom Registry of Link Relations (see section 7.1 of [RFC4287]). When appearing within an atom:entry, the value of the href attribute is an IRI that may be used to modify a media resource associated with that entry.
Remove Section 12
Change Section 7.1 to
<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://purl.org/atom/app#">
<workspace title="Main Site" >
<collection
title="My Blog Entries"
href="http://example.org/reilly/main" />
<collection
title="Pictures"
href="http://example.org/reilly/pic" >
<accept>image/*</accept>
</collection>
</workspace>
<workspace title="Side Bar Blog">
<collection title="Remaindered Links"
href="http://example.org/reilly/list" />
</workspace>
</service>
This Introspection Document describes two workspaces. The first, called
"Main Site", has two collections called "My Blog Entries" and "Pictures"
whose URIs are "http://example.org/reilly/main" and "http://example.org/reilly/pic"
respectively. The "Pictures" includes an accept element indicating that
client may post binary image files to to collection to create new entries.
Entries with associated media resources are discussed in section 8.3.
The second workspace is called "Side Bar Blog" and has a single collection
called "Remaindered Links" whose collection URI is "http://example.org/reilly/list".
Change Section 7.2.2 to:
In an app:workspace element, the first app:collection element MUST refer to the
preferred or primary collecton. In the following example, the "Entries" collection
would be considered the preferred collection.
<service>
<workspace title="My Blog">
<collection title="Entries"
href="http://example.org/myblog/entries" />
<collection title="Photos"
href="http://example.org/myblog/fotes">
<accept>image/*</accept>
</collection>
</workspace>
</service>
Change Section 7.2.3 to:
The "app:collection" describes an Atom Protocol collection. One child element is
defined here for app:collection: "app:accept".
appCollection =
element app:collection {
appCommonAttributes,
attribute title { text },
attribute href { text },
( appAccept?
& extensionElement* )
}
The "app:collection" element MAY appear as a child of an atom:feed or atom:source
element to identify the collection to which new entries may be added to the feed.
Change Section 7.2.4 to:
7.2.4 The "app:accept" Element
The app:collection element MAY contain one "app:accept" element. The app:accept
element value specifies a comma-separated list of media-ranges [RFC2616] identifying
the types of representations that may be POSTd to the Collection's URI. Whitespace
separating the media-range values is considered insignificant and MUST be ignored.
The app:accept element is similar to the HTTP Accept request-header [RFC2616] with
the exception that app:accept has no notion of preference. Accordingly, the value
syntax of app:accept does not use accept-params or "q" parameters as specified in
[RFC2616]. The order of media-ranges is not significant. The following lists are
all equivalent:
<app:accept>image/png, image/*</app:accept>
<app:accept>image/*, image/png</app:accept>
<app:accept>image/*</app:accept>
A value of "entry" indicates that Atom Entry Documents can be posted to the Collection.
If the accept element is omitted, clients SHOULD assume that only Atom Entry documents
will be accepted by the collection. If present, the value of the accept element MUST NOT
be empty and MUST NOT contain leading or trailing whitespace.
appAccept =
element app:accept {
appCommonAttributes,
( ( ("entry" | media-range) ',' )* )
}
Impacts
Actually makes things better
