UserPreferences

PaceMediaEntries5


Abstract

Another hit in the long-running PaceMediaEntries series

Status

Proposed

Rationale

Have an easy-to-explain, easy-to-implement way for uploading binaries and getting an address and a place to wrangle metadata.

Proposal

Replace Section 8 of draft-atom-protocol-08 as follows.

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"). 

  If an entry was created in the collection which received the POST, its URI
  MUST be returned in an HTTP Location header. 

  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.

  Note that since the server is free to alter the posted entry, for example by 
  changing the content of the "id" element, returning the entry as described
  in the previous paragraph may be useful to client software, enabling it 
  to correlate the client and server views of the new entry.

  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.

  The request body of the POST need not be an Atom entry; for example, it 
  might be a picture or a movie.  For a discussion of the issues in posting 
  such content, see 8.4 "Media Resources and Media Link Entries".

8.2 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.

  In particular, the publishing system in this example filled in some values
  not provided in the original POST.  For example, presumably it 
  ascertained the author's name via the authentication protocol used to
  establish the right to post.
  
8.3 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.4 Media Resources and Media Link Entries

  As discussed above, if the body of a client's POST is an Atom Entry
  document, this constitutes a request that the server create a new entry in
  the collection to which the POST is addressed and return its URI. 

  If the body of the client's POST is of a media type other than application/atom+xml,
  this constitutes a request that the server create a new resource as represented by the 
  body of the post, called a "media resource", and also an entry in the
  collection to which the POST was addressed, called a "media link entry", and
  return both URIs.  If the server successfully creates a media resource and media
  link entry pair, the Location header included in the response 
  MUST be that of the media link entry.  The media link entry MUST have a "content" 
  element  with a "src" attribute which links to the media resource.  

  The intent is that the media link entry be used to store metadata about the
  media resource, which might be non-textual, so that the media and the
  metadata can be retrieved and updated separately.

  A media link 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. 

  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. 

  Note that this specification covers the cases when the POST body is an Atom Entry, and
  when it is of a non-Atom media type.  It does not specify any request semantics or 
  server behavior in the case where the POST media-type is application/atom+xml but
  the body is something other than an Atom Entry.
  
8.4.1 Title: Header

  A POST whose body is not of the Atom media type and which thus requests the
  creation of a media resource SHOULD contain a Title: header indicating the client's
  suggested title for  the resource.  For example:

    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, which would
  presumably appear in the media link entry. 

    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.4.2 Example

  Below, the client sends a POST request containing a PNG image 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 {
         undefinedAttribute,
         ( ( ("entry" | media-range) ',' )*  )
   }
   

Impacts

Actually makes things better

Notes


CategoryProposals