[Snowy] Planning minor updates to Tomboy Web REST API, 1.1 draft created on wiki

[Sandy Armstrong <sanfordarmstrong gmail com>]

Hey folks,

This message is mostly intended for developers of server-side and
client-side implementations fo the Tomboy Web REST API.

I have some minor improvements I'd like to make, which I dumped into
bullets at the top here:

http://live.gnome.org/Tomboy/Synchronization/REST/1.1

I'll paste them here in case anyone would like to discuss them:

Things I'd like to add in 1.1:

 * Maybe: have an /api/ endpoint that is guaranteed to contain at
least api-version, so clients don't have to hit /api/1.2/, /api/1.1/,
then /api/1.0/ to figure out that some server only supports 1.0.

 * DEFINITELY add current-sync-guid to all note endpoints (maybe all
endpoints, period?).  Stupid to assume this can't change between
hitting /api/1.1/user/ and /api/1.1/user/notes/.

 * I'd also like to add an {{{include_notes_since}}} parameter to the
notes endpoint.  This would get all notes, but only include content
since the specified version.  This cuts down the number of API calls
required to do a sync by one, because clients need a complete list of
GUIDs to detect server-side note deletion.

 * I don't like {{{include_notes}}} or {{{include_notes_since}}}
names.  Why not {{{include_content}}} as an alias for
{{{include_notes}}}, and {{{include_content_since}}} as an alias for
{{{include_notes_since}}}?  Then again, {{{include_notes}}} brings
more than just content, it brings timestamps/etc.

 * Would it be worthwhile to have API that lets clients specify the
exact fields they care about, instead of only being able to toggle
content?

 * Add a recommendation that clients cache the URL of the notes API
endpoint, and only go through the root->user->notes process when that
URL errors-out.  This is just a hack to reduce server requests on
average.

 * Clarify policy on trailing / ?


Your ideas are welcome, but please keep in mind that sweeping changes
may not be achievable for 1.1 if we want the improvements to make it
into GNOME 3.0 timed releases.


Also, I have reorganized this corner of the wiki a bit

http://live.gnome.org/Tomboy/Synchronization/REST/Original - What was
on the wiki before I started messing around today
http://live.gnome.org/Tomboy/Synchronization/REST/1.0 - Same as above,
edited to reflect that it is a frozen version of the spec, and all
proposed API additions were removed (like supporting XML instead of
JSON, content-version parameters, and a "friends" API)
http://live.gnome.org/Tomboy/Synchronization/REST - Basically a table
of contents for all versions of the spec


Thanks,
Sandy