[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