UserPreferences

PaceMediaEntries2

Abstract

The differences from PaceMediaEntries include:

  1. Section 8.1 "If the server generates a response with a status code of 201 ("Created"), the response SHOULD include an Atom Entry Document representing the newly-created resource."

  2. Section 8.1 "Clients MUST NOT assume that the URI provided by the Location: header can be used to edit the created entry."

  3. Section 8.3 has been changed from a notion of "Media Entries", to "Entries with associated resources". Such resources can be linked to the entry via content/@src or an enclosure link. The common thread is that a link with @rel="edit-resource" is used to edit the associated media resource. This means that folks can still use content/@src to reference the public endpoint of the media resource if they want, but that the edit URI is always specified by the edit-resource link.

  4. Section 8.3 Deleting an entry with associated a media resource(s) should delete the resource(s)

  5. Section 7.x <accept> replaces <member-type> to indicate the types of media resources that can be associated with a collection's entries.

  6. Section 7.2.3 <app:collection> MAY appear as a child of atom:feed or atom:source

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.

In the syndication space, there is a pre-existing notion of entries with enclosures. Podcasting, photocasting, etc all use the enclosure link to associate media resources with entries. Atom defines an enclosure link relation for that very purpose. There is no reason why we cannot leverage that same link here. Rather than having a "Media Collection", in which member resources are any arbitrary media type, we have a collection of entries with associated media resources. A new "edit-resource" link relation is introduced to provide a clean separation between the IRI used for public referencing of the enclosure and the editable representation of the resource.

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.  

  If the server generates a response with a status code of 201 ("Created"), the 
  response SHOULD include 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.

  Responses that contain an Atom Entry Document representing the created resource
  SHOULD contain a Content-Location header with the same 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"
    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 Associated media resources

  Entries may reference associated media resources using either the atom:content 
  element's "src" attribute or an enclosure link relation. Such entries SHOULD 
  contain an atom:link element with a link relation of "edit-resource" that contains 
  the IRI used to modify the linked resource.
  
  To add a 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. 

  Deletion of an entry SHOULD result in the deletion of any associated media resources.
  
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
    User- Agent: Thingio/1.0
    Content- Type: image/png
    Content- Length: nnnn
    Title: An Atom-Powered Robot
  
    ...binary data...
  
  The server MAY ignore the content of the Title: header or modify the suggested title.

    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] [ISO-8859-1] only when encoded according to the rules of [RFC2047] [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
    User- Agent: Thingio/1.0
    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 Atom
  Entry and a representation of that Entry in the body of the response.  The 
  Entry includes one atom:link with a link relation of "enclosure", and
  a second with a link relation "edit-resource", respectively identifying
  the IRI's used for public read-only referencing of the media resource and 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"
    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>
      <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-resource" 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"

Add Section 10.2 

10.2 The "edit-resource" Link Relation

The Atom Protocol adds the value "edit-resource" to the Atom Registry of Link Relations 
(see section 7.1 of [RFC4287]). The value of the href attribute is an IRI that may be used 
to modify a media resource associated with an 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 listing of acceptable media-ranges 
[RFC2616] for media resources associated with a collections entries.  If the
accept element is omitted, clients SHOULD assume that only Atom Entry documents 
will be accepted by the collection.

appAccept =
   element app:accept {
         appCommonAttributes,
         ( ( atomMediaType ',' )*  )
   }

Impacts

Actually makes things better

Notes

CategoryProposals