Fwd: [unhosted] the new 'simple' API

FYI

---------- Forwarded message ----------
From: Michiel de Jong <michiel@unhosted.org>
Date: 6 June 2012 09:47
Subject: [unhosted] the new 'simple' API
To: unhosted <unhosted@googlegroups.com>


the old APIs for remoteStorage are these:
https://www.w3.org/community/unhosted/wiki/remoteStorage-2011.10

the new ones are here:
https://www.w3.org/community/rww/wiki/read-write-web-00

i'm updating ownCloud to
https://www.w3.org/community/rww/wiki/read-write-web-00#webdav and
talking to Francois and Bjarni about updating the surfnet and pagekite
servers to https://www.w3.org/community/rww/wiki/read-write-web-00#simple.

There are four discussion points regarding the new 'simple' API:

- should MKCOL be implicit? In webdav, if you want to create a
document foo/bar/baz, you need to first MKCOL foo, then MKCOL foo/bar
and then PUT foo/bar/baz, unless foo/bar/ already exists. So what the
client-side library does is try to PUT first, and when that gives a
404, backtrack to create ancestor directories. In the simple API we
could make the PUT just succeed, that would save us roundtrips and
saves us one verb.

- should "PROPFIND /" be just "GET /"? in webdav (or at least in
SabreDAV, with webdav you never know which parts are common practice
and which ones are implementation-specific), a GET on a path that ends
in a slash returns 'not implemented'. You have to do PROPFIND to see
the directory listing. I propose to just use GET in the simple API.
saves us another ugly verb.

- should directory listings be xml? creating xml on the server-side is
extra work, and decoding it on the client-side is also extra work. i
propose to skip it, and just immediately give the directory listing.
the JSON format would be a hashmap of filename -> timestamp, where
filename is the document path with the containing directory path taken
off. timestamp should be either the last time a PUT was issued on that
document, or last time a PUT made the contents change (might be easier
to implement for the server and doesn't really matter for the client).
Ccontained subdirectories are indicated with a trailing slash on the
filename, and there the timestamp indicates highest timestamp of any
document or subdir in that subdirectory. the current directory
Example:

GET foo/

might return:

{
   "bar/": 1235467890,
   "boo": 1235467893
}

you could include a timestamp for the directory itself ('.' in unix)
but that doesn't add any information except if you support empty
directories, so let's not do that.

- assuming we do all of the above, then should we support empty
directories? if we don't require MKCOL then the only way to create an
empty directory would be to PUT a dummy document into it, and then
DELETE that, but not delete the directory. then a GET on that
directory would return {} instead of a 404. right now the client-side
library converts 404s to undefined. it could convert 404s on
directories to {}, and then that would discourage at least apps that
use our remoteStorage.js library from relying on empty directories
being distinguishable from directories that were never created yet. i
think empty directories are not useful, so we should not require them.

we can also discuss this further in the chatroom (irc channel).


cheers!
Michiel