Tomboy Web, A RESTful API for Tomboy Note Synchronization

This is the documentation of the 1.0 version of the REST API used by Tomboy, Tomdroid, and Conboy to perform web synchronization with Snowy, Ubuntu One, and Midgard2. Improvements are expected in future versions, but since a Tomboy Web sync add-in shipped in Tomboy 1.0, any updates must keep backwards compatibility in mind.

(A note about REST: As Tomboy notes are interconnected, CRUD of individual note resources has a lot of implications and is not initially supported. The method for updating notes on the server breaks a few REST principles, but is still pretty clean.)

Tomboy's synchronization algorithm is in the process of being documented.

Resources

Responses should be returned in JSON format, as shown in the examples below.

Current spec requires use of OAuth 1.0 or 1.0a for authentication. When fetching temporary credentials, both oauth_consumer_key and oauth_secret (client credentials) have to be hard-coded to anyone. This makes it possible to skip registration of clients on the server.

URIs include "api" , so that you can, for example, visit http://domain/sally/notes/123/new-note-6 and get a pretty interactive web page, then visit http://domain/api/1.0/sally/notes/123 to get the JSON/XML/whatever response.

Another very important note about these URLs: although the spec refers to URLs like api/1.0/user/notes, this exact URL is not required. The only exact URL that is required is api/1.0. When authenticated, that URL will provide a user-ref containing another API URL (which may or may not be api/1.0/user), and the user URL will provide a notes-ref containing yet another API URL (which may or may not be api/1.0/user/notes). Clients of this API must take this into account when developing support for this REST API. Of note, Ubuntu One does not use the exact URLs listed here for users and notes.

http://domain/api/1.0

• Supported HTTP Methods: GET
• Supported query parameters: None

• Response example: http://domain/api/1.0

{
        "user-ref": {
                "api-ref" : "http://domain/api/1.0/sally",
                "href" : "http://domain/sally"
        },
        "oauth_request_token_url": "http://domain/oauth/request_token",
        "oauth_authorize_url": "http://domain/oauth/authorize",
        "oauth_access_token_url": "http://domain/oauth/access_token",
        "api-version": "1.0"
}

user-ref is only visible when the client authenticated via oauth. Unauthenticated clients will not see that field.

Note: Tomboy requests api/1.0 when unauthenticated and api/1.0/ (slash at the end) when authenticated. This is a bug, but servers have to cope with that.

http://domain/api/1.0/user

• Supported HTTP Methods: GET
• Supported query parameters: None

• Response example: http://domain/api/1.0/sally

{
        "user-name": "sally",
        "first-name": "sally",
        "last-name": "walters",
        "notes-ref": {
                "api-ref" : "http://domain/api/1.0/sally/notes",
                "href" : "http://domain/sally/notes"
        },
        "latest-sync-revision": 456   (The latest sync revision from Tomboy, given from last PUT of a note from Tomboy. Give a -1 here if you have not synced with Tomboy yet.),
        "current-sync-guid": "ff2e91b2-1234-4eab-3000-abcde49a7705"   (A uuid generated by the sync application. It should change only if the user decides to clear their sync history from the server and start over with an empty note set.)
}

http://domain/api/1.0/user/notes

• Supported HTTP Methods: GET, PUT
  • A PUT lets you update/add/delete notes in the collection
• Supported query parameters:

  • since - an integer specifying a sync revision number

  • include_notes - a boolean defaulting to False indicating whether or not full note data should be included (I wish I had called this include_content instead. Maybe in a future update to this API we will add include_content as an alias for include_notes, and recommend it instead for clarity)

• Response example: GET http://domain/api/1.0/sally/notes

{
        "latest-sync-revision": 456,
        "notes": [{
                        "guid": "002e91a2-2e34-4e2d-bf88-21def49a7705",
                        "ref": {
                                "api-ref": "http://domain/api/1.0/sally/notes/123",
                                "href": "http://domain/sally/notes/123/new-note-6"
                        },
                        "title": "New Note 6"
                }, {
                        ...(another one)...
                }]
}

• Response example: GET http://domain/api/1.0/sally/notes?include_notes=true

{
        "latest-sync-revision": 456,
        "notes": [{
                        "guid": "002e91a2-2e34-4e2d-bf88-21def49a7705",
                        "title": "New Note 6",
                        "note-content": "Describe your note <b>here</b>.",
                        "note-content-version": 0.1,
                        "last-change-date": "2009-04-19T21:29:23.2197340-07:00",
                        "last-metadata-change-date": "2009-04-19T21:29:23.2197340-07:00",
                        "create-date": "2008-03-06T13:44:46.4342680-08:00",
                        "last-sync-revision": 57,
                        "open-on-startup": false,
                        "pinned": false,
                        "tags": ["tag1", "tag2", "tag3", "system:notebook:biology"]
                }, {
                        ...(another one)...
                }]
}

• Request example: PUT http://domain/api/1.0/sally/notes (response should be the full listing from http://domain/api/1.0/sally/notes )

{
        "latest-sync-revision": 456,
        "note-changes": [{
                        "guid": "002e91a2-2e34-4e2d-bf88-21def49a7705",
                        "title": "New Note 6",
                        "note-content": "Describe your note <b>here</b>.",
                        "note-content-version": 0.1,
                        "last-change-date": "2009-04-19T21:29:23.2197340-07:00",
                        "last-metadata-change-date": "2009-04-19T21:29:23.2197340-07:00",
                        "create-date": "2008-03-06T13:44:46.4342680-08:00",
                        "open-on-startup": false,
                        "pinned": false,
                        "tags": ["tag1", "tag2", "tag3", "system:notebook:biology"]
                }, {
                        ...(another one)...
                }, {
                        "guid": "0bc7b1ef-264f-4aa9-8746-d0f87e9b0176",
                        "command": "delete"
                }]                      
}

http://domain/api/1.0/user/notes/id

• Supported HTTP Methods: GET
• Supported query parameters:
• Not required for sync

• Response example: GET http://domain/api/1.0/sally/notes/123 (Consider dropping "note", also redundant array notation)

{
        "note": [{
                        "guid": "002e91a2-2e34-4e2d-bf88-21def49a7705",
                        "title": "New Note 6",
                        "note-content": "Describe your note <b>here</b>.",
                        "note-content-version": 0.1,
                        "last-change-date": "2009-04-19T21:29:23.2197340-07:00",
                        "last-metadata-change-date": "2009-04-19T21:29:23.2197340-07:00",
                        "create-date": "2008-03-06T13:44:46.4342680-08:00",
                        "open-on-startup": false,
                        "pinned": false,
                        "tags": ["tag1", "tag2", "tag3", "system:notebook:biology"]
                }]
}

Things to Consider When PUT/POSTing Resources

Notes

All fields of a Note object are optional, except the GUID (which need only be a unique string of any length). Let's explore the consequences of setting or not setting Note object fields: