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

[Stuart Langridge <stuart langridge canonical com>]

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. 

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

Agreed with all the rest :)

sil