This is an extension to PaceSimpleResourcePosting, that takes care of metadata. It also shows how PaceLinkParent could be used with resource metadata, and suggests some use for the @src of the content-element.
PaceSimpleResourcePosting is an excellent proposal for eliminating the need for binary content over XML. This makes sense on mobile clients, where plain base64 encoding has an unfortunate side effect of bloating the resulting file size by 33%. Compressing this data on a mobile terminal is not tempting due to the additional overhead.
However, the issue of attaching metadata for the binary content is not addressed in the PaceSimpleResourcePosting. In the future, rich, automatically generated metadata is expected to become commonplace on mobile platforms. Typical metadata includes location, social context (who was present at the time), time, lighting conditions (for later processing), etc.
Most image formats have a built-in extension mechanism for metadata. However, it is different for each binary type, and not all binary types even have a freely extensible mechanism. And for the most part, the metadata comes in different formats as well, making management of it a nightmare, both on the server and on the client side.
Thus we propose to using the Atom mechanism of defining metadata for entries also for binary objects, simplifying the implementations and drawing from the already existing work.
However, since wrapping the XML data together with the binary data is already deemed to be a bad idea (including MIME, which overly complicates parsing), it seems to be necessary to have a second upload for the metadata.
Why cannot we then use entries (i.e. things posted with the PostURI) as such? Two - no, three - reasons: a) Entries are by default displayable. 2) A weblog post should be able to contain multiple images or binary objects. Of course, the binary objects might have differing metadata. iii) Entries, being displayable, have HTML references to the binary objects. These references are different depending on the type of the content - an applet would be referred to using the <applet> -tag, and image with <img>, something else perhaps with <a> or <object>. This is not an optimal way of referring to the objects, as it is difficult to later on determine what is the relation of the binary objects and the post.
It should also be noted that there are some media types, most notably SMIL, which by its nature is a single entity, yet is always composed of multiple parts. This means that it must be possible to tie multiple uploads (if multipart is not possible) into a single entity. The impact of naturally multi-part content on this proposal is not yet fully analyzed.
Why not DAV?
Well - DAV is fine, but for the most part the clients rarely need to do anything complicated with the binary objects and metadata. It also complicates the client when it needs to do two protocols - especially when the client is a mobile one, and you would really like to do just a simple implementation.
Refactor, refactor, refactor
The binary content is uploaded using POST verb to the ResourcePostURI, as specified in the PaceSimpleResourcePosting. The returned Location URI is then used to manipulate the object.
The metadata relating to the previously uploaded resource is then added using PUT to the Meta-Location URI returned by the POST method, as a standard Atom <entry>.
The Meta-Location URI can then be manipulated using as if it were a standard EditURI for entries. The only difference between this and a weblog post is that the server considers this entry to be undisplayable metadata. However, in some cases (like an image gallery), it might be considered to be displayable as well.
Additions to Atom API
The ResourcePostURI is used to create new non-entry resources. The client POSTs a resource of the desired MIME type directly to this URI. If the request is successful then the server returns a new unique URI where a representation of the resource may be retrieved. The URI returned MUST be suitable for use in a subsequent HTTP GET and MUST return the resource data originally uploaded.
In addition, a GET or a HEAD to the URI returned MUST always return the Meta-Location header, pointing at the metadata of the object.
(As in PaceSimpleResourcePosting).
However, in addition to the Location -header, the server returns a "Meta-Location" -header, which points to an URI which can be used then to manipulate the metadata of the binary object. This functions exactly like the EditURI of a normal entry, except that the metadata is associated to the binary, and is NOT shown as a post on the web site.
The PostURI for the metadata is not required, as it is implicitly created when uploading a binary using the ResourcePostURI.
The client may also remove the content and any associated metadata by sending a DELETE to the URI.
When the resource has been posted using a POST, the metadata is added with a subsequent PUT, e.g.
PUT /_do/exampleblog/binaries/id=123 HTTP/1.1 Host: www.example.com <entry xmlns:loc="http://some.somewhere.com/ns/location-api" xmlns:loc="http://xmlns.com/foaf/0.1/"> <title>My beautiful picture</title> <link rel="parent" href="http://uri-of-image-here" /> <loc:x>1.234</loc:x> <loc:y>2.345</loc:y> <loc:humanreadable>North Pole</loc:humanreadable> <loc:present> <foaf:Person> <foaf:Name>Santa Claus</foaf:Name> </foaf:Person> </loc:present> </entry>
The link rel="parent" is optional, and only displays the potential usage with the PaceLinkParent proposal.
The expected status codes from a PUT are 200, 400, and 500. 401, 404, and 410 are also possible.
5.x.3.1 200 OK
The PUT of the metadata was successful.
Indicates that the server believes that that data sent constitutes an invalid request. A short description of the error will appear on the status line itself. A longer description will appear in the body.
Indicates that the server detected an internal error on the server processing this request (such as an unhandled exception). A short description of the error will appear on the status line itself. A longer description will appear in the body.
Clients need to do relatively complex multipass posting for even simple posts.
There is little or no difference to a metadata <entry> and a regular weblog post <entry>. The endpoints are different so that the server knows that metadata is a non-entry resource, and not to be mismatched with an actual weblog post.
Since the metadata is handled in the same way as an entry, corresponding to the exact same semantics, and editable with the same EditURI, it has to be able to refer to the "parent" object somehow. Thus, a GET of the metadata entry might look something like this:
<entry xmlns:loc="http://some.somewhere.com/ns/location-api" xmlns:loc="http://xmlns.com/foaf/0.1/"> <title>My beautiful picture</title> <link rel="parent" href="http://uri-of-image-here" /> <id>1823912830912893</id> <modified>2004-07-04T16:49:59Z</modified> <issued>2004-07-04T16:49:59Z</issued> <created>2004-07-04T16:49:59Z</created> <loc:x>1.234</loc:x> <loc:y>2.345</loc:y> <loc:humanreadable>North Pole</loc:humanreadable> <loc:present> <foaf:Person> <foaf:Name>Santa Claus</foaf:Name> </foaf:Person> </loc:present> <content src="http://uri-of-image-here" type="image/jpeg"/> </entry>
A typical case where the user wishes to post three images into a blog entry should go like this:
1. Client POSTs the first picture using the ResourcePostURI, and notes the returned URI. 2. Client fills in the necessary metadata to an Atom <entry>, and PUTs it to the returned URI. 3. Client repeats steps 1-2 for three images. 4. Client rewrites the user-created entry to point at the images, i.e. the src references of the <img src=""> tags. 5. Client POSTs the weblog entry using the PostURI.
The PaceLinkParent should probably be used to generate an entry -> binary -> metadata relationship. This would mandate a "post binary", "post entry", "post metadata" order, unless the "rev" -attribute of <link rel="parent"> is supported.
This method is also compatible with WebDAV. The URI returned by the POST to the ResourcePostURI could also serve as a DAV endpoint, and allow the use of the PROPFIND and PROPPATCH methods. This would allow more fine-grained control, while retaining compatibility between the Atom syntax proposed here and the DAV syntax: obviously, a GET to the Meta-Location EditURI should return the same data set as PROPFIND.
13-Jul-04: Changed the proposal to use the Meta-Location -header, thanks to the suggestion by KenMacLeod. This makes the overall structure clearer. It also allows for WebDAV compatibility, since the DAV methods can now be applied directly against the binary.