UserPreferences

PaceUseLinkHeaders2


Abstract

Reworking of existing Section 8 and the original PaceUseLinkHeaders.

At the cost of increased verbage, this pace seeks to address a number of issues of the existing -06 draft. Please do not reject the pace simply due to its length; it can always be refactored that it is shorter.

Key points:

<entry>
  ...
  <link rel="alternate" title="Use this in links" type="image/jpeg" href="http://example.org/images/abc123" />
  <link rel="edit" title="Use this to edit the jpeg" type="image/jpeg" href="http://example.org/images/abc123/edit" />
  <link rel="edit" title="Use this to edit the metadata" type="application/atom+xml" href="http://example.org/images/abc123/edit.atom" />
  <content type="image/jpg" src="http://example.org/thumbnails/abc123.jpg" />
  ...
</entry>
HTTP/1.1 200 OK
Date: Fri, 16 Dec 2005 17:17:17 GMT
Content- Length: nnnn
Content- Type: image/jpeg
Link: <http://example.org/media/abc123.jpg>; rel="edit"; 
  type="image/jpeg", <http://example.org/media/abc123.jpg/atom>;
  rel="edit", type="application/atom+xml"
  
{binary image data}

Status

Withdrawn

Rationale

Much of the existing Section 8 description of Collections is both confusing, underspecified and generally inadequate. The lack of an even optional ability to edit the metadata of media collections resources is a significant hole in the spec. The relationship between the entries listed in the collection feed and the member resources they represent is underspecified and there are unnecessary inconsistencies in the way media and entry resources are listed -- entry collections use link elements while media collections use the content element. alternate and edit links should be sufficient for media collections also, freeing up the content element for other useful things (such as providing a thumbnail of a member image file).

Proposal

8. Collections

Collections consist of sets of member resources. This specification defines two types of collections: Entry Collections and Media Collection.

Entry Collections are resource sets that restrict their membership to Atom Entry Documents and are identified in the introspecton document by having an app:member-type value of "entry". New member entries are created by POSTing a representation of the new Atom Entry Document to the URI of the collection. The returned Location header specifies a URI where the created Atom Entry may be retrieved. Servers MAY choose to allow clients to create new members of an Entry Collection by POSTing resource representations other than valid Atom Entry Documents. Atom Entry Documents POSTed to an Entry Collection MUST be syntactically valid as defined by [RFC4287].

Media Collections are resource sets whose membership is unconstrained and are identified in the introspection document by having an app:member-type value of "media". New member resources are created by POSTing a representation of the resource (e.g. image file, word processing document, recording audio, etc) to the URI of the collection. The returned Location header specifies a URI where the created resource may be retrieved. Servers MAY choose to reject POSTed resource representations of various media content-types.

Clients should note that Servers MAY choose to modify the metadata and content of resources POSTed to a collection (including the atom:id of POSTed Atom Entries). Because the created resources may differ from that originally posted by the client, clients MUST retrieve an editable representation of the resource from the server before attempting to modify the resource.

Collections contain any number of editable member resources. A collection's URI MAY be used to both create new members and to request a listing of existing members.

A successful GET request on the Collection URI MUST return an Atom Feed Document, each entry of which represents an individual member of the collection. Because a collection's member set may be extremely large, servers MAY choose to return only a partial listing of its membership in response to the GET request. Partial listings MAY include link elements clients can use to retrieve listings of additional member resources as specified in {ref to section on List Paging}.

The listing returned by the server is logically equivalent to listing the members of a directory on a file system. That is, each entry in the feed is a description of and a reference to a resource but does not represent an editable representation of that resource and may not contain the full content of the member resource. Further, the entries contained in the feed may reference resources of any media type. For instance, a collection consisting entirely of JPEG images will return an Atom feed whose contained atom:entry elements contain a URI and metadata for each of the member JPEG images. The metadata included in the listing about a resource is determined by the server and may or may not be modifiable by the client.

If the member resource is editable, it's entry in the listing feed MUST contain at least one atom:link element with a rel attribute value of "edit" whose href attribute specifies a URI where an editable representation of the resource may be retrieved. If a given resource has multiple editable representations, multiple "edit" links MAY be specified using the link attribute to identify the content-type of the representation. For instance, a listing entry for a JPEG image might include two edit links -- one that may be used for retrieving and editing the binary image data and a second that may be used for retrieving and editing an Atom Entry Document describing the image.

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  ...
  <entry>
    ...
    <link rel="edit" type="image/jpeg"
          href="http://www.example.org/media/abc.jpg" />
    <link rel="edit" type="application/atom+xml"
          href="http://www.example.org/media/abc.jpg.atom" />
    ...
    <content type="image/jpeg" src="http://www.example.org/media/abc.jpg" />
  </entry>
</feed>

New members are added to the collection by POSTing a representation of the resource to the Collection IRI. A successful creation POST MUST return a Location header whose value is the URI of the newly created resource. This URI SHOULD be considered suitable for use in linking to the created resource (e.g. using hypertext links, HTML img tags, etc). The server MAY choose to allow clients to use the URI for editing the resource.

If the created resource is editable, the server MAY choose to include an HTTP Link Header in the creation response with a rel parameter value of "edit" whose value identifies a URI clients may use to edit the resource. The Link header MAY contain a "type" parameter whose value identifies the media content-type of the editable representation. If a resource has multiple editable representations, multiple Link headers MAY be included.

Servers MAY choose to include an Atom Entry Document describing the created resource in HTTP response. This entry SHOULD be identical to the member resource's entry in the listing feed retrieved by GETing the Collection URI. The fact that a server MAY return an Atom Entry Document in response to the creation of a resource does not imply that a permanent Atom Entry Document resource was created for the member.

Below, the client requests to add a new JPEG image to a collection by POSTing a representation of the image to the Collection URI.

POST /media-collection-uri HTTP/1.1
Host: example.org
Content- Type: image/jpeg
Content- Length: nnnn

{binary image data}

Successful creation MAY be indicated by a 201 Created response that includes the required Location header indicating the permanent location of the created resource and the optional edit Link header identifying a URI where the resource may be edited. While in this example the Edit URI and resource Location happen to be the same, client MUST NOT assume that the resource Location URI will always be suitable for edit operations and SHOULD check for the existence of edit links.

HTTP/1.1 201 Created
Date: Fri, 16 Dec 2005 17:17:17 GMT
Content- Length: 0
Location: http://example.org/media/abc123.jpg
Link: <http://example.org/media/abc123.jpg>; rel="edit"; 
  type="image/jpeg"

Performing a GET request on the Collection URI would return an Atom feed listing the newly created image resource. The URI of the newly created JPEG member resource is provided by the alternate link in the atom:entry.

HTTP/1.1 OK
Date: Fri, 16 Dec 2005 17:17:17 GMT
Content- Length: nnnn
Content- Type: application/atom+xml

<feed xmlns="http://www.w3.org/2005/Atom">
  ...
  <entry xmlns="http://www.w3.org/2005/Atom">
      <id>tag:example.org,2005:/media/abc123.jpg</id>
      <title>Title Extracted from EXIF Data</title>
      <link href="http://example.org/media/abc123.jpg"
            type="image/jpeg" />
      <link href="http://example.org/media/abc123.jpg" 
            type="image/jpeg" rel="edit" />
      <updated>2003-12-13T18:30:02Z</updated>
      <author>
        <name>Author Name Extracted from EXIF</name>
      </author>
      <summary>Description Extracted from EXIF</summary>
  </entry>
</feed>

In the second example below, the client requests the creation of a new Atom Entry resource by POSTing the entry to a second collection. The content of the entry references the JPEG image created in the previous example.

POST /entry-collection-uri HTTP/1.1
Host: example.org
Content- Type: application/atom+xml
Content- Length: nnn

<entry xmlns="http://www.w3.org/2005/Atom">
    <id>tag:example.org,2005:/the_resource</id>
    <title>A vacation photo</title>
    <updated>2003-12-13T18:30:02Z</updated>
    <author><name>John Doe</name></author>
    <summary>A photo from my vacation in Europe</summary>
    <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <p>A picture from my vacation in Europe</p>
        <img src="http://example.org/media/abc123.jpg" 
             alt="A vacation photo" />
      </div>
    </content>
</entry>

Once again, successful creation is indicated by a 201 Created response that includes the required Location header indicating the permanent location of created resource and a single edit Link header identifying the URI where the resource may be edited.

HTTP/1.1 201 Created
Date: Fri, 16 Dec 2005 17:17:17 GMT
Content- Length: 0
Location: http://example.org/the_resource
Link: <http://example.org/the_resource>; rel="edit"; 
  type="application/atom+xml"

Performing a GET request on the Collection URI would return an Atom feed listing the newly created resource.

HTTP/1.1 OK
Date: Fri, 16 Dec 2005 17:17:17 GMT
Content- Length: nnnn
Content- Type: application/atom+xml

<feed xmlns="http://www.w3.org/2005/Atom">
  ...
  <entry xmlns="http://www.w3.org/2005/Atom">
    <id>tag:example.org,2005:/the_resource</id>
    <title>A vacation photo</title>
    <updated>2003-12-13T18:30:02Z</updated>
    <author><name>John Doe</name></author>
    <link href="http://example.org/the_resource" />
    <link href="http://example.org/the_resource" 
          rel="edit" type="application/atom+xml" />
    <summary>A photo from my vacation in Europe</summary>
    <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <p>A picture from my vacation in Europe</p>
        <img src="http://example.org/media/abc123.jpg" 
             alt="A vacation photo" />
      </div>
    </content>
  </entry>
</feed>

Clients retrieve representations of member resources using GET requests on the URI's specified by atom:link elements contained in the listing feed atom:entry elements. Link elements with a rel attribute value of "alternate" identify permanent, referenceable locations of member resources that are suitable for use in linking to the resource from other locations (e.g. HTML img tags, hyperlinks, etc). Link elements with a rel attribute value of "edit" identify URI suitable for performing edit operations (DELETE, PUT, etc) on the resource.

When a client retrieves an alternate representation of an editable resource, the server MAY include an HTTP Link header identifying a URI suitable for performing edit operations against the resource. If a resource has multiple editable representations, multiple edit Link headers MAY be used.

For instance, below a client retrieves the JPEG image created in the previous example:

GET /media/abc123.jpg HTTP/1.1
Host: example.org

Because the image is a member of an APP Collection, the server response includes a Link header referencing the location where the JPEG image may be edited.

HTTP/1.1 200 OK
Date: Fri, 16 Dec 2005 17:17:17 GMT
Content- Length: nnnn
Content- Type: image/jpeg
Link: <http://example.org/media/abc123.jpg>; rel="edit"; 
  type="image/jpeg"
  
{binary image data}

When a client retrieves an editable representation of a resource, the server SHOULD include one or more HTTP Link Headers specifying alternate referenceable and edit URI's for the resource. For instance, in the example response below, the server uses the Link header to specify alternate public and edit URI's for the image.

HTTP/1.1 200 OK
Date: Fri, 16 Dec 2005 17:17:17 GMT
Content- Length: nnnn
Content- Type: image/jpeg
Link: <http://example.org/media/abc123.jpg>; rel="edit"; 
  type="image/jpeg", <http://cdn.example.org/media/abc123.jpg>; 
  type="image/jpeg"
  
{binary image data}

Impacts

Notes


CategoryProposals