Abstract
-
Eliminate the distinction between media collections and entry collections
-
Replace the "member-type" with an "accept" attribute that specifies which types of representations are accepted by the collection
-
Explicitly state that POST response payload is optional
-
Explicitly state that the media-type of the resource created by a POST MAY differ from the media-type of the POSTed representation
Status
Withdrawn. Replaced by PaceReplaceTypeWithAccept2
Rationale
I've been receiving a lot of feedback that the existing media collection stuff in -06 is confusing and complicated. For one, it is unclear what exactly is created when a media resource is POSTed to a collection and whether or not the HTTP response to the POST MUST contain an atom:entry. Also, it is unclear whether and how the created media resource is editable.
For instance, in one scenario, a document library client wants to upload a Word document and assign it to multiple categories and tags. The client does not want to have to create two entries in two different collections to do this. They simply want to upload the word document then modify that specific resources metadata to indicate the categorization. -06 provides absolutely no way for that to happen. At the same time, the protocol needs to continue to support the simple photo post use case. This Pace allows for both.
This Pace proposes eliminating the distinction between media and entry collections. There are simply collections to which resources are posted. It is up to the server to determine what kinds of resources are created in response. So, if a client POSTs a word document, the collection *could* choose to either just save that word document and return its URI to the client (Example 1 below) OR save that word document somewhere and create an editable atom:entry that points to that document (Example 2)
Proposal
Modify collection element definition to
appCollection =
element app:collection {
appCommonAttributes,
attribute title { text },
attribute href { text },
attribute accept { text }
( extensionElement* )
}
Replace section 7.3.4
7.3.4 The 'accept' Attribute The 'accept' attribute indicates the types of resources which MAY be POSTed to the Collection IRI. Its value is a comma-separated list of media-types and media-ranges with optional parameters as defined in section 14.1 of [RFC2616] as the field value of the accept request header.
Replace section 8
8.0 Creating resources with POST
Resources are created when a client POSTs a representation of the desired resource to the
IRI of the collection. Collections MAY impose constraints on the media-types that are
created in a collection and MAY generate a response with a status code of
415 ("Unsupported Media Type"). The media-type of the created resources MAY differ from
the media-type of the representation POSTed to the Collection IRI.
A successful creation POST MUST return a Location: header with the URI of the newly
created resource. The payload of the HTTP Response MAY contain a representation of the
newly created resource.
Below, the client requests to create a resource in a collection:
POST /edit HTTP/1.1
Host: example.org
User- Agent: Thingio/1.0
Content- Type: application/atom+xml
Content- Length: nnn
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<updated>2003-12-13T18:30:02Z</updated>
<summary>Some text.</summary>
</entry>
The resource is created by sending an Atom Entry as the entity body.
Successful creation is indicated by a 201 created response and includes a Location: header.
HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content- Length: 0
Location: http://example.org/edit/first-post.atom
Example Introspection
<app>
<workspace ...>
<collection
title="photos"
href="http://example.net/binary/edit/"
accept="image/*" />
<collection
title="entries"
href="http://example.net/blog/edit/"
accept="application/atom+xml" />
</workspace>
</app>
Example 1: Simple image post
Post the picture
POST /binary/edit/ HTTP/1.1 Host: example.net User-Agent: Thingio/1.0 Content- Type: image/png content- Length: nnnn Title: A picture of the beach ...binary data...
Response indicating successful creation of the image
HTTP/1.1 201 Created Date: Fri, 25 Mar 2005 17:17:11 GMT Content- Length: nnnn Location: http://example.net/binary/image1.png
Post the blog entry
POST /blog/edit/ HTTP/1.1
Host: example.net
User-Agent: Thingio/1.0
Content- Type: application/atom+xml
Content- Length: nnnn
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>What I did on my summer vacation</title>
<updated>2005-09-02T10:30:00Z</updated>
<summary>Beach!</summary>
<content type="xhtml" xml:lang="en">
<div xmlns="http://www.w3.org/1999/xhtml">
<p>We went to the beach for summer vacation.
Here is a picture of the waves rolling in:
<img
src="http://example.net/binary/image1.png"
alt="A picture of the beach."
/>
</p>
</div>
</content>
</entry>
Example 2: Posting binary data results in a new atom:entry
In Example 1, posting the binary file JUST created the binary file resource with no editable metadata. Alternatively, posting a binary file could result in the creation of an editable atom:entry whose content element references the binary file.
Post the picture
POST /blog/edit/ HTTP/1.1 Host: example.net User-Agent: Thingio/1.0 Content- Type: image/png Content- Length: nnnn Title: A picture of the beach ...binary data...
Response indicating that an atom:entry was created.
HTTP/1.1 201 Created
Date: Fri, 25 Mar 2005 17:17:11 GMT
Content- Length: nnnn
Content- Type: application/atom+xml
Location: http://example.net/binary/image1.atom
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>A picture of the beach.</title>
<link rel="edit"
href="http://example.net/binary/image1.atom"/>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-568596895695</id>
<updated>2005-09-02T10:30:00Z</updated>
<summary>Waves</summary>
<content type="image/png"
src="http://example.net/binary/image1.png"/>
</entry>
Update the Atom entry for the image (e.g. change the title, summary, etc)
PUT /binary/image1.atom HTTP/1.1
Host: example.net
User-Agent: Thingio/1.0
Content- Type: application/atom+xml
Content- Length: nnnn
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Vacation 2005 - The Beach</title>
<link rel="edit"
href="http://example.net/binary/image1.atom"/>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-568596895695</id>
<updated>2005-09-03T10:30:00Z</updated>
<summary>A picture of the beach from Vacation 2005</summary>
<category scheme="http://example.net/vacation/" term="2005" />
<category scheme="http://example.net/tags/" term="beach" />
<category scheme="http://example.net/tags/" term="vacation" />
<content type="image/png"
src="http://example.net/binary/image1.png"/>
</entry>
Impacts
Eliminates the confusing distinction between media and entry collections.
Notes
see PaceCollectionsAcceptedMediaTypes (some language in this pace was taken from that one)
