> On Tue, 2011-12-20 at 10:35 -0500, Brian Waldon wrote: > >> So there obviously isn't one clear way to version a RESTful API. Not >> every API is created equal, and therefore doesn't need the same >> capabilities in its versioning mechanism. At this point, it is >> important to determine what specifically the Compute API needs: >> >> - Our versioning mechanism should not hinder progress within the underlying >> implementation >> - We need to be able to iterate on the design of our API without being tied >> down >> - It needs to be simple to use from the point of view of API developers AND >> language bindings authors >> >> With those goals in mind, I would like to propose we adopt the >> following mechanism: >> >> - Use only major versions >> - Allow backwards incompatibility between major versions >> - Expose version of response in Content-Type header >> (application/vnd.openstack.compute.v3+json) >> - Form request with version in Accept/Content-Type headers >> - If no version is provided in request, default to stable >> - If an unsupported version is requested, provide a 300 Multiple Choices >> response w/ list of available versioned mimetypes >> - Provide a mechanism that can communicate all supported mimetypes (versions) > > There are clearly lots of different approaches that could be taken and > this looks as reasonable as any other. > > Just a couple of points I'd make: > > - Versioning is important, but I'd prefer us to place more emphasis > on how to design the API such that we can continue to expand the > API in compatible ways for a decent period without introducing a > new major version e.g.
Absolutely agree. > - capability discovery - clients should not assume the API > supports a given feature, but should query for its availability > at runtime Do you see the current extensions mechanism as a complete solution to this problem? > - opaque URI structure - by requiring clients to navigate links > in the hypertext documents returned by the server, you can > change things around without breaking well-written clients. > Basically, a good rule is that a client should never need to > construct a URI I think the missing link here is a root resource that provides links to get clients into top-level resources (servers, images, etc). Right now, the only client I've worked on doesn't follow links (python-novaclient). > - versioning of resources - if we versioned individual resources, > we could introduce a new incompatible version of a single > resource without affecting users of other resources. So I'm not completely sold here, but the mechanism I have proposed is open-ended enough that we could do this if we have enough reason to do so. I think this adds a lot of complexity from the client's point of view once they have to track multiple versions of multiple resources. > - The whole question of media types is worthy of a long discussion, > e.g. > > https://fedorahosted.org/pipermail/rhevm-api/2010-April/thread.html#94 > > https://www.redhat.com/archives/rest-practices/2010-April/thread.html#00004 > > Those discussions run the whole gamut of the topic, from whether > media types should be fine or coarse grained, how to make > compatible changes in XML, schema implications, URI based > versioning schemes, etc. > > If we go with media type based versioning, it would definitely make > more sense as a parameter e.g. > > Accept: application/vnd.openstack.compute+json;version=3 > > Also, I'd support versionless application/xml and application/json > to make things dirt simple for trivial one-off clients. Yep, I'm for a default (unversioned media type). However, I'm against using version as a param. I will admit I've only looked at webob, but it seems like it is uncommon for libraries to parse accept params other than 'q' and 'level'. > - The big argument for URI based versioning is that not all clients > (e.g. browsers) can participate in content type negotiation. I'm > not convinced that's a huge issue, though. Yeah, I don't want to have my hands tied by this requirement. I think we can define defaults to allow browsers to participate, but that's where I would draw the line. Brian _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : [email protected] Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
