Fix Media Collections in Draft-08
It's great that a media resource can have an associated atom entry for editing metadata, however, the way this is defined, after posting the image, the client would either have to hope that the server included the generated Atom entry in the response to the POST operation (an undefined behavior) or do a GET on the collection-uri, dig through the entries to find the one that matched the image they just posted, look for the edit link, etc. Solution: return an edit Link header in the response:
Link: <http://example.org/media/1.png?edit>; rel="edit"
The other problem with media collections is that they are unusable in scenarios where the public referenceable uri is different than the edit uri. Solution: limit Location to editing, use a Link header to optionally point to alternative public read-only references. The Location URI MAY still be used for public referencing.
Location: http://example.org/media/1.png Link: <http://cdn.example.org/photos/1.png>; rel="alternate"
Complete example response:
HTTP/1.1 201 Created Date: nnnn Location: http://example.org/media/1.png Link: <http://example.org/media/1.png?edit>; rel="edit", <http://cdn.example.org/photos/1.png>; rel="alternate"
The Link headers would also be returned in response to GET and HEAD operations on the URI specified by Location.
Add to Section 8.3
The response to a POST to a Media Collection creating a resource or the response to a GET or HEAD on the URI of the media resource URI MAY contain a Link header with a "rel" parameter value of "edit" that contains the URI of an Atom Entry document representing the metadata of the member resource. A client MAY use this to edit the metadata associatd with the resource. The response MAY also include zero or more Link headers with a "rel" parameter value of "alternate" that specify alternative URI's that can be used for publicly referencing the member resource.
Modify section 8.3.1
Change: "When creating a public, read-only reference to the member resource, a client SHOULD use this value." to "When creating a public, read-only reference to the member resource, a client MAY use this value."
Fix the example in Section 12
POST /binary/edit/ HTTP/1.1 Host: example.net User-Agent: Thingio/1.0 Content- Type: image/png Content- Length: nnnn Title: A picture of the beach ...binary data... The member resource is created and an HTTP status code of 201 is returned. An alternate read-only URI is provided in the response. HTTP/1.1 201 Created Date: Fri, 25 Mar 2005 17:17:11 GMT Content- Length: nnnn Content- Type: application/atom+xml Location: http://example.net/binary/edit/b/129.png Link: <http://example.net/photos/123.png>; rel="alternate" The client then POSTs the Atom Entry that refers to the newly created image resource. Note that the client takes the URI http://example.net/photos/129.png and uses it in the 'img' element in the Entry content: POST /blog/edit/ HTTP/1.1 Host: example.net User-Agent: Thingio/1.0 Content- Type: application/atom+xml Content- Length: nnnn <?xml version="1.0" encoding="utf-8"?> <entry xmlns="http://www.w3.org/2005/Atom"> <title>What I did on my summer vacation</title> <link href="http://example.org/atom05"/> <id>urn:uuid:1225c695-ffb8-4ebb-aaaa-80da354efa6a</id> <updated>2005-09-02T10:30:00Z</updated> <summary>Beach!</summary> <content type="xhtml" xml:lang="en"> <div xmlns="http://www.w3.org/1999/xhtml"> <p>We went to the beach for summer vacation. Here is a picture of the waves rolling in: <img src="http://example.net/binary/readonly/129.png" alt="A picture of the beach" /> </p> </div> </content> </entry>