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>
