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

[Rodrigo Moya <rodrigo gnome-db org>]

On Tue, 2010-09-28 at 21:41 -0700, Sandy Armstrong wrote:
> 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.
> 
it sounds ok to me, so servers will have to have URLs for all the API
versions they support then? If so, /api/ should probably return a list
of the API versions they support, so that clients can pick the one they
prefer, right?

>  * 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/.
> 
yes

>  * 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.
> 
right

>  * 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?
> 
hmm, and pass it as HTTP parameters? I think it might make sense, but it
might make the URLs a bit more complicated than they are now. I am
personally happy with what we have now, you get the basic fields by
default, and all the extra information if you include the
include_content argument

>  * 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.
>