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.
* 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.
* 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. 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
* 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.
* 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.
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
_______________________________________________
deltacloud-devel mailing list
[email protected]
https://fedorahosted.org/mailman/listinfo/deltacloud-devel
