UserPreferences

PaceUseLinkHeaders


Abstract

Allows for the use of Link headers to point to non-editable representations of media resources.

Allows for the use of Link headers to point to editable metadata for media resources.

Status

Proposal

Rationale

-06 Currently does not allow for editable metadata on media resources. For instance, once an image has been posted, there is no way to specify any categorization, description, etc. This pace recognizes that not all implementations require media resources to have editable metadata by making it possible for a server to use a Link header to optionally point to some other URI where the metadata can be edited.

Further, -06 Currently requires that the HTTP response to a POST contain an atom:entry payload in order to determine the "read-only" or "public" version of a posted resource. This Pace makes it possible to use a Link header to reference the location of "public", non-editable representations of the media resource.

See the examples for illustrates of how this works.

Proposal

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 nthe media-type of 
the representation POSTed to the Collection IRI.

A HTTP Response indicating 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

8.1 Editable Metadata

A server creating a resource in response to an HTTP POST MAY choose to allow clients to
edit metadata associated with the resource.  For instance, if a client POSTs an image 
file to a collection, the server MAY generate an associated Atom Entry Document that
contains title, description, update and categorization metadata about the image.

Servers MAY indicate the URI of editable metadata using a Link: header with a "rel"
parameter value of "edit".  The resource representation identified by the URI of 
the Link header SHOULD be an Atom Entry Document.

Below, the client requests to add a new PNG image in a collection.

POST /images HTTP/1.1
Host: example.org
User- Agent: Thingio/1.0
Content- Type: image/png
Content- Length: nnnn

-- binary data --

The response includes the required Location header indicating the location of the
created resource and a Link header indicating a URI that may be used to edit an
Atom Entry Document associated with the image.

HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content- Length: 0  
Link: <http://example.org/images/image1.atom>; rel="edit"
Location: http://example.org/images/image1.png

A Client may update the metadata for the resource by sending a HTTP PUT containing
an Atom Entry Document to the URI specified by the edit Link header.

8.2 Non-editable Representations

A server creating a resource in response to an HTTP POST MAY choose to expose 
non-editable representations of the created resource.  Servers MAY indicate 
the URI of such representations using a Link: header with a "rel" parameter value
of "external".

Below, the client requests to add a new PNG image in a collection.

POST /images HTTP/1.1
Host: example.org
User- Agent: Thingio/1.0
Content- Type: image/png
Content- Length: nnnn

-- binary data --

The response includes the required Location header indicating the location of the
created resource and a Link header indicating the URI of a non-editable
representation.

HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content- Length: 0  
Link: <http://cdn.example.org/images/image1.png>; rel="external"
Location: http://example.org/images/image1.png

Note that multiple Link headers may be specified using HTTP header 
concatentation, for instance:

Link: <http://example.org/images/image1.atom>; rel="edit",
 <http://cdn.example.org/images/image1.png>; rel="external"

Example 1: Simple Cat Picture Post

This is the simplest example that does NOT expose any editable metadata or "external" representations

POST /images HTTP/1.1
Host: example.org
Content- Type: image/png
Content- Length: nnnn

-- binary data --

Response

HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content- Length: 0  
Location: http://example.org/images/image1.png

Cat-Blog Post. Image URI pulled from Location header.

POST /entries HTTP/1.1
Host: example.org
Content- Type: application/atom+xml
Content- Length: nnnn

<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom">
  ...
  <content type="html">
    ...
    <img src="http://example.org/images/image1.png" />
  </content>
</entry>

Example 2: Simple Cat Picture Post with Non-editable representation

This example uses the non-editable representation link.

POST /images HTTP/1.1
Host: example.org
Content- Type: image/png
Content- Length: nnnn

-- binary data --

Response

HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content- Length: 0  
Link: <http://mycdn.example.org/images/image1.png>; rel="external"
Location: http://example.org/images/image1.png

Cat-Blog Post. Image URI pulled from "external" Link header.

POST /entries HTTP/1.1
Host: example.org
Content- Type: application/atom+xml
Content- Length: nnnn

<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom">
  ...
  <content type="html">
    ...
    <img src="http://mycdn.example.org/images/image1.png" />
  </content>
</entry>

Example 3: Simple Cat Picture Post with editable metadata

Note: this pace makes this *OPTIONAL*.

POST /images HTTP/1.1
Host: example.org
Content- Type: image/png
Content- Length: nnnn

-- binary data --

Response

HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content- Length: 0  
Link: <http://example.org/images/image1.atom>; rel="edit"
Location: http://example.org/images/image1.png

GET the Atom Entry Document representing the editable metadata (using the URI from the "edit" Link)

GET /images/image1.atom HTTP/1.1
Host: example.org

Server responds with an Atom Entry Document

HTTP/1.1 200 OK
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content -Type: application/atom+xml
Content -Length: nnnn

<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>tag:example.org,2005:/images/image1.png</id>
  <title>image1.png</title>
  <summary />
  <updated>2005-10-07T17:17:11Z</updated>
  <content type="image/png" 
           src="http://example.org/images/image1.png" />
</entry>

Client Updates the metadata for the image

PUT /images/image1.atom HTTP/1.1
Host: example.org
Content- Type: application/atom+xml
Content- Length: nnnn

<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>tag:example.org,2005:/images/image1.png</id>
  <title>My Cat</title>
  <summary>This is my cat</summary>
  <updated>2005-10-07T18:17:11Z</updated>
  <category scheme="http://example.org/tags/" term="cat" />
  <category scheme="http://example.org/tags/" term="pets" />
  <category scheme="http://example.org/category" term="personal" />
  <content type="image/png" 
           src="http://example.org/images/image1.png" />
</entry>

When the Client GET's the Atom Feed that lists the members of the Collection, the atom:entry representing this image would reflect the modified metadata

GET /images HTTP/1.1
Host: example.org

Response

HTTP/1.1 200 OK
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content -Type: application/atom+xml
Content -Length: nnnn

<?xml version="1.0" ?>
<feed xmlns="http://www.w3.org/2005/Atom">
  ...
  <entry>
    <id>tag:example.org,2005:/images/image1.png</id>
    <title>My Cat</title>
    <summary>This is my cat</summary>
    <updated>2005-10-07T18:17:11Z</updated>
    <category scheme="http://example.org/tags/" term="cat" />
    <category scheme="http://example.org/tags/" term="pets" />
    <category scheme="http://example.org/category" term="personal" />
    <content type="image/png" 
             src="http://example.org/images/image1.png" />
  </entry>
  ...
</feed>

Impacts

Notes


CategoryProposals