[rest-practices] Variable responses

[David Lutterkort]

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>


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.

My question to the list: does anybody have experience with doing this
kind of variable responses ?

David