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>