[rest-practices] [deltacloud-devel] Towards declaring the Deltacloud API stable

[Mark McLoughlin]

Hey,

Just as context for others, on the rest-practices mailing list we've
been trying to hash out some sort of consensus on a set of that
deltacloud and other related APIs could follow. Here's the in-progress
result of that:

  http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide

Cross-posting is evil, but I think it's worthwhile including
rest-practices on this since so much of it is useful stuff to consider
for all APIs.

On Wed, 2010-05-05 at 17:17 -0700, David Lutterkort wrote:
> Hi,
> 
> I would like to get quickly to a point where we can declare the current
> Deltacloud API stable, and be reasonably confident that we can evolve
> the API in a way that will maintain backwards compatibility.
> 
> Unfortunately, there are a few goofups in the current Deltacloud API
> that we need to fix before we can declare the API stable, since fixing
> them will break API compatibility. In no specific order, the issues I am
> aware of are
> 
> 
>       * returning full objects when listing a collection: this is a
>         pretty serious issue. For example, for Terremark, returning a
>         list of full image details requires first calling to Terremark
>         to get a list of images without details, then retrieving the
>         detail of each image. That can be a long and slow process,
>         leading to timeout issues for clients. The best way to fix this
>         is to return full image details on GET /api/images from drivers
>         where that is cheap, and only an abbreviated list of images,
>         i.e. with only a URL and id for the image, from drivers like
>         Terremark. We'll probably have to deal with other lists in a
>         similar manner.

Very interesting ... and your solution certainly sounds reasonable.

Related, with the RHEV-M API we're experimenting with making both the id
and href attributes, which would work out nice here:

  GET /api/images HTTP/1.1

  <images>
    <image id="1234" href="/api/images/1234"/>
    <image id="9876" href="/api/images/9876"/>
    ...
  </images>

rather than:

  GET /api/images HTTP/1.1

  <images>
    <image href="/api/images/1234">
      <id>1234</id>
    </image>
    <image href="/api/images/9876">
      <id>9876</id>
    </image>
    ...
  </images>

>       * returning the representation of a new instance from a
>         POST /api/instances: again, in some drivers, like Terremark,
>         that requires making two calls to the backend cloud, which is
>         too fragile for this operation. Instead, the result from
>         POST /api/instances should contain the URL of the new instance
>         in a Location: header, and optionally the instance
>         representation for drivers where that is cheap to do.

Reasonable - the instance representation in the response could be
considered a convenience thing only.

>       * the list of actions for an instance is misleading: we report
>         <link rel='ACTION' href='URL'/> - that is not enough, since it
>         gives no indication what HTTP method should be used to perform
>         the action.

To some extent, I think it should be implicit which method should be
used - and, in this case, we're using POST because we're creating a new
"action instance".

Then again, though, HTML forms specify whether to GET or POST ...

>         It's generally POST, but for destroying an instance,
>         you are supposed to do a DELETE on the instance URL. We
>         therefore need to include a method in the <link/> tag

I don't follow you there ... where will you add method="DELETE"?

do you mean:

  <resource href="uri-for-this-resource">
    <actions>
      <link rel="delete" href="uri-for-this-resource" method="DELETE"/>
      ...
    </actions>
  </resource>

If so, I'd again say the method is implicit ... that's what DELETE means
for all resources ... and you can document it pretty plainly e.g.

  https://fedorahosted.org/rhevm-api/wiki/CommonIdiomsForResources

>       * inconsistent indication of relations to other objects, e.g. the
>         image and the hardware profile for an instance. For the image,
>         we just include a <image href="..."/> tag, whereas for hardware
>         profile we give the URL for hte HWP and its id. There's actually
>         some discussion on rest-practices[1] pertaining to that, though
>         we haven't reached any conclusion.

My vote is that the server should return <image id=".." href=".."/> in
its representations, but if the client is supplying a reference it
should only be required to supply <image id="..."/>

>       * inconsistent usage of '-' and '_' in XML tag names (e.g.,
>         <hardware-profile> vs. <owner_id>) This one is mostly cosmetic,
>         but if we are breaking API, we might as well fix this one, too.

We went for under_score in rhevm-api

Cheers,
Mark.

> I am sure there are other issues, and I'd appreciate if people could
> help collect them, so we can address them with one last big API breakage
> before we declare the API stable going forward.
> 
> David
> 
> [1] https://www.redhat.com/archives/rest-practices/2010-April/msg00024.html