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

[Sandy Armstrong <sanfordarmstrong gmail com>]

On Wed, Sep 29, 2010 at 1:41 AM, Stuart Langridge
<stuart langridge canonical com> wrote:
> On Wed, 2010-09-29 at 10:22 +0200, Rodrigo Moya wrote:
>> On Tue, 2010-09-28 at 21:41 -0700, Sandy Armstrong wrote:
>> >  * 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?
>
> I agree here -- ideally all servers will support all API versions until
> the end of time (and we'll certainly need to support 1.0 until 2015),
> but it's possible that old API versions might get deprecated (for age,
> or for unresolveable security problems), so it'd be good to explicitly
> say which API versions a server supports. /api/ isn't an endpoint right
> now and it's the obvious place to put this, so +1 from me.

Good point guys, that makes sense to me.

>> >  * 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
>
> I...am not sold on this idea, for two not-very-good reasons. The first
> is that it's a RESTish API, which means you ask for the state of a
> resource; you're not supposed to ask for some arbitrary subset of the
> state of a resource :) The second is that I can see a future where
> someone fetches fields1,2,3 for a note, and then says: I want to PUT
> that subset of the note back to change some but not all fields for that
> note. That's a complicated nightmare, and having subset note retrieval
> but not subset note saving is a bit of a wart.

Actually, we already support PUTing a minimal amount of fields.
That's what this table is about:

http://live.gnome.org/Tomboy/Synchronization/REST/1.0#Things_to_Consider_When_PUT.2BAC8-POSTing_Resources

The reason I put thought into this was because some clients may not
care about things like pinned state, open-on-startup, etc.  They may
not store the original values, and therefore not be able to include
them in a PUT that updated the content.  Also, we may add fields and
still want to support older clients that don't know about thew new
fields, so we'd still end up in a situation where some clients are not
PUTing every field of a note.

That being said, we don't have a solid use case for subset note
retrieval so there's probably no point in adding it right now.

Thanks for all your input guys, please let me know if you run across
anything else.

Oh, and Stuart, you might be interested in:
http://github.com/sandyarmstrong/snowy/tree/html5

Sandy