Alex Hudson
2011-03-18 12:25:48 UTC
This is more really a set of notes given a discussion between Lance,
Steve, SEJeff, and some others on IRC.
The original Dragonfly schema was REST-inspired, but in many ways not
RESTful:
http://bongo-project.org/Guides/Dragonfly_URL_Schemes
The main problem I have with this schema is that it ties the web server
implementation very much to the UI implementation on the front end:
everything is defined more or less as the UI displays it, which is a
clear red flag to me.
I was going to propose something which is actually closer to how things
work in the Store - so that the same interface (I'll call it an API)
applies no matter whether you're accessing mails, contacts, or some
other form of content (this was raised when talking about Tomboy notes
really).
I think versioning the API and stuff is sensible, so as a starting point
I'd proffer the base URI of http://server/bongo/api-1.0/ - everything
below would hang off that.
The way the store works right now is that you have these top-level
groups of data - called user stores - so that would be the first set of
resources that you'd access. Under that store, you have collections, and
under collections you have documents.
I propose that we wouldn't access anything by name/path within the
store, but simply by ID, so all resource paths would look something
like:
/store-name/collection_or_documentID
So, for example, we know that ID 0x1 is always the 'root' collection, ID
0x6 is always /mail/INBOX. Not all collections have static IDs, of
course, but those key first IDs give you discovery.
As an example:
GET http://server/bongo/api-1.0/_system/1
might return
{
meta-data: {
id: '0000000000000001',
type: 4096,
ctime: 1220527135,
filename: '/'
},
data: [
{
id: '0000000000000002',
type: 4096,
ctime: 1220527135,
filename: '/addressbook'
},
....
]
}
.. which represents a directory listing of /. I'm not totally sure about
separating data: and meta-data: that's not very RESTful. Ideally, we'd
put meta-data in the HTTP headers as X-Bongo-Id: etc., but to be honest
I'm not absolutely sure that would work for all clients.
Special stuff for collections.
When we're doing lists, we probably want to be able to filter somehow,
and we certainly want to be able to paginate (maybe by default). I think
these things ought to be GET parameters, because if we stuck some of
this stuff in the URI it would again break REST (harming caching, for
one).
Special stuff for documents.
It's almost certain we would want some documents in different
representations. Whereas contacts and things are stored internally as
JSON, we may also need vCard versions or whatever. The resource URI
wouldn't change, again you'd have some kind of parameter specifying what
MIME type of data you're actually looking for.
I think also we'd want to have some way of opening up MIME-encoded
documents so that you could address the content inside of them. I'm
proposing to hand-wave over that for now: there are caching issues
again, there are also other issues like supporting HTTP byte ranges,
download resumption, and other cool stuff. I'd like to pretend that
problem doesn't exist right now.
Doing it.
The cool thing about the above is that we already have a basic PHP
implementation that could be hooked up to do something like this quite
quickly; Lance is also looking at a Ruby based system to present a more
cohesive web UI which could do things a PHP implementation couldn't
(websockets spring to mind).
Does anyone have any comments about the above?
Ta
Alex.
--
This message was scanned by Better Hosted and is believed to be clean.
http://www.betterhosted.com
Steve, SEJeff, and some others on IRC.
The original Dragonfly schema was REST-inspired, but in many ways not
RESTful:
http://bongo-project.org/Guides/Dragonfly_URL_Schemes
The main problem I have with this schema is that it ties the web server
implementation very much to the UI implementation on the front end:
everything is defined more or less as the UI displays it, which is a
clear red flag to me.
I was going to propose something which is actually closer to how things
work in the Store - so that the same interface (I'll call it an API)
applies no matter whether you're accessing mails, contacts, or some
other form of content (this was raised when talking about Tomboy notes
really).
I think versioning the API and stuff is sensible, so as a starting point
I'd proffer the base URI of http://server/bongo/api-1.0/ - everything
below would hang off that.
The way the store works right now is that you have these top-level
groups of data - called user stores - so that would be the first set of
resources that you'd access. Under that store, you have collections, and
under collections you have documents.
I propose that we wouldn't access anything by name/path within the
store, but simply by ID, so all resource paths would look something
like:
/store-name/collection_or_documentID
So, for example, we know that ID 0x1 is always the 'root' collection, ID
0x6 is always /mail/INBOX. Not all collections have static IDs, of
course, but those key first IDs give you discovery.
As an example:
GET http://server/bongo/api-1.0/_system/1
might return
{
meta-data: {
id: '0000000000000001',
type: 4096,
ctime: 1220527135,
filename: '/'
},
data: [
{
id: '0000000000000002',
type: 4096,
ctime: 1220527135,
filename: '/addressbook'
},
....
]
}
.. which represents a directory listing of /. I'm not totally sure about
separating data: and meta-data: that's not very RESTful. Ideally, we'd
put meta-data in the HTTP headers as X-Bongo-Id: etc., but to be honest
I'm not absolutely sure that would work for all clients.
Special stuff for collections.
When we're doing lists, we probably want to be able to filter somehow,
and we certainly want to be able to paginate (maybe by default). I think
these things ought to be GET parameters, because if we stuck some of
this stuff in the URI it would again break REST (harming caching, for
one).
Special stuff for documents.
It's almost certain we would want some documents in different
representations. Whereas contacts and things are stored internally as
JSON, we may also need vCard versions or whatever. The resource URI
wouldn't change, again you'd have some kind of parameter specifying what
MIME type of data you're actually looking for.
I think also we'd want to have some way of opening up MIME-encoded
documents so that you could address the content inside of them. I'm
proposing to hand-wave over that for now: there are caching issues
again, there are also other issues like supporting HTTP byte ranges,
download resumption, and other cool stuff. I'd like to pretend that
problem doesn't exist right now.
Doing it.
The cool thing about the above is that we already have a basic PHP
implementation that could be hooked up to do something like this quite
quickly; Lance is also looking at a Ruby based system to present a more
cohesive web UI which could do things a PHP implementation couldn't
(websockets spring to mind).
Does anyone have any comments about the above?
Ta
Alex.
--
This message was scanned by Better Hosted and is believed to be clean.
http://www.betterhosted.com