launchpad-dev team mailing list archive

[Robert Collins <robert.collins@xxxxxxxxxxxxx>]

On Thu, Nov 25, 2010 at 3:50 AM, Aaron Bentley <aaron@xxxxxxxxxxxxx> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 11/23/2010 06:07 PM, Gary Poster wrote:
>> On Nov 22, 2010, at 10:48 AM, Aaron Bentley wrote:
>
>>> The current strategy is to expose the developer API via the web, and
>>> AIUI, that's not something we plan to change.
>>
>> Actually, a change here is one of the things we're working on proposing, at least for collections.  Entities will probably still be exposed as they are now.
>
> Is this a separate change from Rob's "Group based approach" from the
> "Lower query counts via different code structure" thread?

Yes, separate but analogous and driven by similar imperatives.

>>> (In fact, Robert has
>>> suggested that Launchpad itself should actually use the web API, which
>>> would make the developer API identical to the web API.)
>>
>> I've heard this, and was interested in it.  I'm now pretty skeptical that this is reasonable.  Transactions, for instance, are very useful in a database.  They can be exposed in a webservice, but are not natural for it.

I totally agree that transactions are not natural for a webservice,
and I would need a /lot/ of convincing to feel happy about putting a
transaction concept into the on-wire format of the webservice. However
a PATCH operation for many objects at once makes a great deal of sense
simply from a performance perspective, and perhaps that, with whatever
degree of atomicity we choose to offer, would be enough.

> I share your skepticism, but it seems like there's a renewed push to be
> AJAX-y, and if we follow that to the logical extreme, we'll be doing
> everything using the web API via Javascript.

If we *could* write the Launchpad web UI servers as a thin shim on top
of the web API, it would mean several things:
 - our APIs are sufficiently fast and capable that other interesting
UIs can be built on them
 - we could scale (and structure) our rendering separately from our DB access
 - slow rendering wouldn't affect API availability - because they'd be
separated (vs now where the same cluster that sometimes takes 12+
seconds rendering something with many rows)

>>> So I think you
>>> do need to think like a developer, except perhaps for the most trivial
>>> scripts.
>>
>> If "think like a developer" means "you have to read the Launchpad source code"
>
> No, I don't mean that.  I think you need to write programs, not
> "scripts", with real data structures and careful flow of control, to get
> stuff done.  You need to understand the API pretty much the same way we
> do.  And heck, following our python style guide isn't a terrible idea.
> At least, it makes your program more readable to Launchpad developers.
>
>> In some cases even that was insufficient when I tried to use some Soyuz APIs.  I hope we can change that.  I would like more uniformity and more documentation, and we're working on both.
>
> So, if we get improved Soyuz documentation for the web API-- the kind
> that explains domain models and such, wouldn't that also be useful for
> the python API?

Gary was talking about putting the output from the newer doctest like
thing - actual docs, not 'tests' - nicely formatted and themed, up on
help.launchpad.net - as a reference for folk wanting to know about our
data model and concepts. I think this is a great idea.

But it really seems to me that docs 'for our users' and docs 'for us'
are different things, and having them on separate wikis is useful
because it avoids adding confusion - like logs of rosetta design
decisions from 3 years back - showing up in searches.

-Rob