[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Option #6: Using POST for uploading associated resources


All,

Option #6 is to use a simple POST to upload individual resources to a feed, separately from the Atom entry which references them. This note explains how #6 could be implemented, and the pros and cons. I am going to steal shamelessly from Mark Nottingham's presentation for option #1 in order to talk about option #6 below.

* Uploading Resources

The first step for a client is to discover a URL that tells it where it can upload resources associated with a given feed. One way would be as in Mark's proposal; the details aren't critical for this proposal, but if we used <link> it could look like this:

<link rel="base.post_resource" href="http://www.example.com/_do/exampleblog/post_resource"/>

The client then POSTs data to this URL, not specifying anything more specific about where the resource is supposed to go other than "with this feed":

---8<---
POST /_do/exampleblog/post_resource HTTP/1.1
Host: www.example.com
Content-Type: image/jpeg
Content-Length: nnn

... image here, transmitted as raw bytes ...
-->8--

The server takes the data, stores it somewhere, and returns an HTTP 201 Created status giving an arbitrary URL where the content ended up:

---8<---
201 Created
Location: http://www.example.com/exampleblog/_resources/imgAE3767EE4561234.jpg
-->8---

The server simply made up a unique name for the newly created resource, giving it an appropriate extension. This is because the client said it didn't care what the final URL of this associated resource was. This would be appropriate, for example, for small inline images like smileys where few really care what the name of the image file is. Or really, any scenario where you are dealing with what the user sees as a compound document.

After this point, the client is in the same position as with WebDAV: It has the URL where a resouce is stored, and may need to swizzle IMG SRC attributes in the chunk of HTML it's about to post as an actual entry to an Atom feed. Since this is common to any option where clients upload multiple parts (both #1 and #6), I'll skip that detail here.

(If the entry really just consists of the picture itself, and perhaps some Atom metadata, the entry would consist of the metadata plus an indirect reference: <content location="http://www.example.com/exampleblog/_resources/imgAE3767EE4561234.jpg"; /> , for example. This would perhaps be the case more commonly for things like PDF documents.)

That's pretty much it for the simplest case.

Note: The Location header returned MAY have a host name different from the server POSTed to if the server desires. For example, to offload image storage/serving to a farm of servers optimized for the task:

---8<---
201 CREATED
Location: http://is42.example.com/exampleblog/_resources/picture.jpg
-->8---

* Client Hinting

Another option the client would have is to try to specify a relative name for the resource. Here's how this could work, repurposing the Content-Location header as a hint to the server:

---8<---
POST /_do/exampleblog/post_resource HTTP/1.1
Host: www.example.com
Content-Type: image/jpeg
Content-Length: nnn
Content-Location: picture.jpg

... image here ...
-->8--

In this case, the client is saying "here's a resource, and I'd like it named picture.jpg if possible; please give me its full URL when you're done."

(Note that this is using Content-Location: in a previously unused way; see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html. Content-Disposition: is another candidate but I can't find a mention of its use outside of MIME parts. This new usage is sort of similar to its use in MHTML MIME, if you squint hard enough. Another option would be some kind of URL parameter on the POST URL. It's not critical, so I'll assume Content-Location: is usable unless proved otherwise for the following.)

The response to this is again a 201 CREATED:

---8<---
201 CREATED
Location: http://www.example.com/exampleblog/_resources/picture.jpg
-->8---

Note that in this case, the server honored the (relative) Content-Location request. In other cases, it might not. For example, if there's a name collision, it might give back ".../_resources/picture2.jpg". A server MAY ignore the Content-Location field entirely.

Content-Location could contain paths and even full absolute URLs; servers MAY pick and choose from pieces of the Content-Location hint as they see fit.

Pros:

o Simple and direct. Clients use only HTTP POST, which they have to do anyway to use Atom.
o Allows binary transfer of large resources, as opposed to encoding-in-XML approaches which require a 33% expansion for base64 encoding.
o Allows for intelligent restarts of uploads when uploading multiple parts
o Allows for use of chunked encoding for things like video streams (scary...)
o Content-Location hint is optional to make nicer URLs but doesn't constrain servers that need flexibility to place content elsewhere
o Simple one-stop protocol for clients who really just want to upload a compound document with pictures from point A to point B
o Compared to WebDAV, is simpler and lighter weight
o Compared to WebDAV, no possibility of namespace collision for resources (consider the multiple author case) and no need for client workarounds to avoid same.

Cons:

o It's not as full featured as WebDAV; it solves only the uploading problem; it doesn't allow for full control of a namespace by the client (but that might be a pro for the server side...)
o Doesn't solve the binary-content-in-XML problem at all (not a goal of this solution)
o Requires URL rewriting by the client
o If user really just wants to upload a picture with a little metadata, requires two uploads: this one, plus an Atom entry with some sort of "no, look over here!" link inside. o Authentication for upload would have to be HTTP-based (Basic or Digest auth?) rather than something more XML-based, unless I'm missing something.

My take:

This approach could serve as a _basic_ mechanism for getting resources uploaded to a feed efficiently, and possibly could be required of Atom servers, though they could provide other mechanisms (like WebDAV) as well.

-John Panzer