[rest-practices] Variable responses

Mark McLoughlin markmc at redhat.com
Wed May 12 09:40:12 UTC 2010


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

Cheers,
Mark.




More information about the rest-practices mailing list