launchpad-dev team mailing list archive

[Leonard Richardson <leonard.richardson@xxxxxxxxxxxxx>]

> 1) We want to be able to retrieve one or multiple page fragments after making 
> a model change through the web service (either PATCH or named operation).
> 
>    (For example, subscribing a user means that maybe two or three parts of the 
> page will need to be updated.)
> 
> 2) We want to reuse the presentation logic already coded in the regular web UI 
> views.
> 
>    (We already have views that know how to render the different parts that 
> needs to be updated on the page.)
> 
> 3) We want to provide a very productive API for front-end developers to use. 
> (Minimize amount of web-service specific glue needed, minimize the amount of 
> confusing asynchronous requests that needs to be done).
> 
> So one solution we found out was to basically drop the way HTML representation 
> are currently implemented for something much simpler and much more powerful.
> 
> Instead of wiring server-side one-to-one individual web-service resources to 
> an HTML representation, we should basically let the AJAX client decide what 
> should be returned from the web service call.
> 
> The client would request that one or more views be rendered after the 
> successful completion of the API call and their results returned to the 
> client.
> 
> We could use the accept-extension to the Accept header to specify the list of 
> views to return results.
> 
> Something like:
> 
> Accept: application/x-page-fragments;views="subscribers=+subscriber-portlets, 
> count=+subscribers-count"
> 
> That should return a JSON dictionary containing two keys: subscribers 
> containing the result of the +subscriber-porlets view and count containing the 
> result of the +subscribers-count view.
> 
> That removes the wiring that has to be done now server side to map these 
> existing views to the HTML representation of fields, removes the problematic 
> limitation of having only HTML representation and allows us to retrieve 
> efficiently all the fragments we need on the page.

This seems like a good design and simple enough to implement. We are
already doing one adapter lookup for an HTML representation (at least
for PATCH), so we would start doing multiple named adapter lookups.

From a theoretical standpoint my main objection is that
"+subscriber-portlets" and "+subscribers-count" look like magic strings.
Given that I understand how application/x-page-fragments works, how am I
supposed to know that I can pass in those strings and no other strings?
With a directory of available views, developers will know what's
available and it'll be easy to make sure we have good test coverage.
Without it, the HTML views will be another piece of magic that you can't
understand without being an experienced Launchpad developer.

It's easy to say "so we'll create a directory", but we'd need to figure
out the best way to do it. The directory of views, or at least a link to
it, would need to be present in the WADL, so that our human-readable
documentation can include it.

Since it's clear you need this, I don't want to delay it by demanding a
directory (especially since I don't have time to work on this), but I
also don't want to end up with a two-tiered system where some parts of
our web service are well-documented and understood by everyone, while
other parts are only comprehensible to Launchpad developers.

Apropos Aaron's comment:

> If we're rethinking this stuff, it would be really nice to do further
> latency-hiding on the request side.  For example, I have a plugin that
> 1. logs in
> 2. looks up branch lp:foo
> 3. looks up branch lp:bar
> 4. looks up person ~baz
> 5. creates a merge proposal for merging lp:foo into lp:bar, with ~baz
> as a reviewer.
> 6. opens the local browser to the merge proposal URL.
> 
> Steps 1-4 have no data dependencies, so they could easily be done as a
> single request.

There's no fundamental reason why steps 2-4 need to trigger HTTP
requests. launchpadlib has some deferred loading code but it's clearly
not being triggered in your case. I'd prefer to make launchpadlib
smarter than to bundle requests that deal with multiple objects. (HTTP
pipelining is OK, but I don't know if that's what you were thinking.)

Leonard

Attachment: signature.asc
Description: This is a digitally signed message part