launchpad-dev team mailing list archive

[Martin Pool <mbp@xxxxxxxxxxxxx>]

On 2 June 2011 03:10, Aaron Bentley <aaron@xxxxxxxxxxxxx> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 11-06-01 12:02 PM, Barry Warsaw wrote:
>> On Jun 01, 2011, at 10:23 AM, Aaron Bentley wrote:
>>
>>> In simple REST implementations, the fact that every URL is an object can
>>> be a significant performance issue, because you must access them once at
>>> a time, instead of as a group.  If we go this route, we should be sure
>>> that it's easy do do things like retrieving a ProductSeries and its
>>> linked branch in a single call.
>>
>> You do that by defining a resource that represents the group of things you
>> want to operate on.  It can be tricky sometimes, but it's doable.
>
> Oh, absolutely.  I was pointing out a pothole that we can certainly
> avoid if we are careful.
>
> On the other hand, we could wind up with too many groups if we took that
> approach.  And rather than defining such groups in advance, a system
> that gave us the flexibility to define the group we need at call-time
> might be a better solution.
>
> e.g. not
>
> http://launchpad.net/+productseries-and-branch/foo
>
> but
>
> http://launchpad.net?productseries=%22foo%22&branch=productseries/branch

The CouchDB book has I think a good description of this denormalizing
approach near the start, which includes the idea of considering of
putting into the document what you would expect or want to see in a
human-oriented web page or paper form about that document: we don't
make human users go to a different URL to find out about each task on
a bug, so nor should rest api clients.  I think an API can reasonably
have an opinion about what makes sense to include by default; then
later you can perhaps have options about whether or not to include
things that would be large, expensive, or infrequently used.  If all
the LP APIs included most of the information shown on the UI pages
they correspond to, that would be a step forward.

>> BTW, lazr.restful is only REST-ish because it defines backdoor function calls.
>
> Yes, and this makes me doubt that pure REST is actually a good way to do
> RPC.  Dirty REST?  Maybe...

I think the good bits of REST are (and they mesh together):

 * think in terms of remote resources that are manipulated, rather
than remote procedure calls
 * actually use the http verbs, rather than just running everything
over POST: if you want to just read, just GET
 * if possible, express things as idempotent or non-mutating
operations; GET again being a good example
 * separate out "what object am I acting on" into the URL; as distinct
from the parameters of the operation you want to do on it
 * think about the URLs and think about what is transferred on each transaction
 * the objects are (up to a certain level) self describing and have
hyperlinks for <http://en.wikipedia.org/wiki/HATEOAS>; I say "up to a
certain level" because they probably shouldn't include human-oriented
semantic description

I think it is a very naïve view of REST to say that each resource must
be exactly one stand alone application-domain object; it is almost
guaranteed to perform poorly and there is no point using the name
"REST" for an architecture that can never work well.

Martin