Guides/Dragonfly URL Schemes

[edit] Introduction

Dragonfly is designed with a REST architecture, with the goal that every interesting slice of a user's data has a URL that can be used to request or edit that data, as appropriate. These URLs are designed to be used "behind the scenes" by http clients to access bongo data in standard formats such as json, ical, vcard, and rss.

One such client is the Dragonfly web client, which is the primary web interface for bongo. One driving goal of this client is to expose these benefits of the REST design to users by providing them with URLs that can be bookmarked, returned to, shared, and compatible with other tools which are aware of URLs such as IM clients, mail clients, launchers, and so forth. A simple example of this is that a user should be able to set their bongo summary page as their browser home page.

Thus, there are two distinct, but related, types of URLs used within Dragonfly: server URLs which are used to request data from the Dragonfly web server and client URLs which are used by the Dragonfly client to return to a view. Since the Dragonfly client is run within the context of a single web page, each client URL begins with the path to the Dragonfly page. The rest of the url follows the anchor hash #. So, when Dragonfly is loaded into a browser, it decodes the information after the hash (client URL) to figure out which data to display and then requests the data from the server (using the server URL) and then renders it to the page. There is intended to be a tightly coupled relationship between client and server URLs, however this breaks down at times in the code as it exists at the moment.

[edit] Components of URLs

Side by side, the URL schemes are:

Server: host[:port]/user/username/tab/set/handler/arg1/arg2/.../argN.format

Client: host[:port]/#~username/tab/set/handler/arg1/arg2/.../argN

tabs are literally what you might see at the side of the Dragonfly user interface. They include things like addressbook, calendar...

sets are tab specific things like inbox, personal...

handlers are TODO like subscriptions, tome...

Some handlers expect arguments that request certain bits of data like 2006/12/6...

format is an extension that is used to describe the format. The Dragonfly web client uses JSON as its transfer format, so most (all?) handlers can provide json representations by adding a .json extension. This is designed to be extensible to other formats including ICS, VCS, and RSS.

The following table lists some combinations of tabs, sets, and handlers that are, more or less, understood by the code at the moment. The starred (*) items are defaults, and are used when a - is given in the URL instead of a name:

[edit] Examples

Requesting page one of the conversations in the inbox in JavaScript Object Notation format:

http://server2:8080/user/admin/mail/inbox/conversations/page1.json

This example's options are:

• tab: mail
• set: inbox
• handler: conversations
• arg1: page1

[edit] Other notes

In the Dragonfly source code, sets are named collections.