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