[rest-practices] Variable responses

[Bryan Kearney]

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