launchpad-dev team mailing list archive

[Martin Pool <mbp@xxxxxxxxxxxxx>]

I had a bit of a go at this over the weekend.  It is gratifyingly fast
compared to what I expect to see with launchpadlib clients, just
through doing fewer requests and not unnecessarily blocking on them.
I like that a lot.

The code is in <http://launchpad.net/wrested> and lp:wrested.

For instance:

 ./wrestler.py https://api.launchpad.net/devel/bugs/1
 ./wrestler.py https://api.launchpad.net/devel/bzr/'?ws.op=searchTasks'

(Try it!)

It's early days but I really like how it's shaping up.  I think it is
less error-prone than the approach taken by txrestfulclient, because
you never get half-initialized objects: if you have the resource, it's
valid.  I'm finding it also nicer to work with than launchpadlib
because you never get unexpected pauses: all network io is explicit.

It seems to me it would be healthy for Launchpad for people to be
looking at what the actual http interface is, rather than using a
black-box client.  <https://help.launchpad.net/API/Hacking> was a
great resource (thanks.)

The basic approach is that you ask for an object and get a deferred,
which will eventually deliver the object you requested.  For
collections, you pass a consumer which will be fed objects as they
arrive.

I can see this fitting very well with what's described in
<https://dev.launchpad.net/LEP/WebservicePerformance>.

I am trying to keep a separation between Launchpad-specific policy and
REST in general; though I'm not quite sure yet how many conventions
are standard and how many Launchpad has made up for itself.

It has a nerd-oriented gtk explorer test harness:
<http://www.flickr.com/photos/mbp_/5386185146/> which can open an
arbitrary URL, click through links to other objects, and stream reads
of collections, including very large collections like "all the bugs."
All these capabilities are of course also exposed in the library api.

It should do, but doesn't yet:
 * authenticated requests
 * socket reuse
 * caching
 * anything to do with the WADL
 * (a bunch of other things in the TODO)

I have mixed feelings about WADL.  As a systematic way of documenting
an API, and something from which you can produce apidoc html or
whatever it's fine.  As something applications will read _at run time_
it seems a bit strange: the application will be written assuming
particular APIs are present and if they are not, or if other APIs do
turn out to be present, the application is not likely to suddenly make
use of them.  An application that did want to cope with differing
server capabilities would probably be better off just sending requests
and coping with errors.

But perhaps an exception to this is an explorer-type application which
does want to show all the methods you, the interactive user, could
possibly call if you wanted to.  That leads me to think it should be
something applications can opt in to, if they want to introspect the
interface.  It does seem wrong to me that applications should need to
download over a megabyte of data when it can't really change their
behavior.

That leaves open the question of how a client ought to call methods,
like say <https://api.launchpad.net/devel/bzr/?ws.op=searchTasks>.  It
would be ugly to have random client apps hardcode that.  (It's also
ugly to have, as at present in launchpadlib, them necessarily fetch
<https://api.launchpad.net/devel/bzr/> first when they don't want to
know about the product itself, only its bug tasks.)

(Incidentally, I wonder why we don't have eg a
bug_tasks_collection_link on products, which seems a bit more in
keeping with a REST-ish style.)

So it's quite fun and I intend to continue.  If someone wants to talk
about it I'd like that too.

-- 
Martin