[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: [rest-practices] Variable responses



On 05/12/2010 05:40 AM, Mark McLoughlin wrote:
On Thu, 2010-05-06 at 16:40 -0700, David Lutterkort wrote:
This might be an issue that is specific to Deltacloud Core; it's
definitely caused by two aspects of Deltacloud that make it different
from most other REST services:

       * Deltacloud Core is stateless (on the server side)
       * Deltacloud Core is an adapter around other API's

The specific issue is that for some operations, we'd like to return
responses with varying levels of details. Two specific issues:

Listing all images
------------------

When listing all images available in a cloud (GET /api/images), we
currently return a list that contains full details for each image.

That's not a workable approach for some of the backend clouds we talk
to, since it forces the Deltacloud server to make n+1 requests to the
backend cloud (one for the abridged list of images, n more to get
details about each image) - for some backend clouds (e.g., Terremark)
that becomes unacceptably slow, to the point where we need to worry
about clients timing out.

At the same time, we'd still like to return full details about images
when that is possible cheaply (e.g., when Deltacloud talks to EC2) to
save clients from having to make n+1 calls to get full image details.

What I would like to do is make the result for GET /api/images vary, so
that for some clouds, you'd get

         <images details="full">
           <image href="..">
             .. full details for the image ..
           </image>
           ... more images ...
         </images>

and for others you'd only get

         <images details="none">
           <image href="...">
             <id>...</id>
           </image>
           ... more image references ...
         </images>

The general principle here is that a resource's full representation is
only guaranteed to be available from the resource's URI

A client should always be prepared to de-reference the resource's URI if
it feels some data is missing

Creating a new instance
-----------------------

In a similar vein, right now, when creating a new instance with a
POST /api/instances, we return the full XML representation of the new
instance. For some clouds (again, Terremark is the posterboy), this
actually requires two calls inside the Deltacloud driver: one to create
the instance, and one to retrieve the details of that new instance.
Besides being a little slow, this is also very fragile, in that the
instance creation might succeed, but retrieving details might fail,
making it, at the very least, hard to indicate to the client what just
happened.

For that case, too, I'd like to change the API definition so that you
will always get the URL for the instance details in a Location: header
or abridged XML in the body, and full details only when they can be
provided cheaply.

As in, a POST or PUT should not be required to return a representation
of the resource in the body. If it does, it's only an optimization,
otherwise the client should deference the URI in the Location header

I think both of those work well
Is there a standard which frameworks expect? I think that basic save logic in activeresource would be fine with this.

For that matter, do we have a list of current viable REST toolsets? It would be good to have this as means of testing how the standards work across the tool chains. An API standard is nice, having it work in the exisiting frameworks is nicer.

We have been using the following for clients:

Python:
- Custom using Net:http

Ruby:
- Custom
- Active Resource

Java
- Jersey
- RestEasy

-- bk



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]