UserPreferences

PaceReplaceTypeWithAccept


Abstract

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)


CategoryProposals