On 12/10/2011, at 12:51 AM, Mark McLoughlin wrote: > > - Version numbers aren't necessarily the best way to advertise the > availability of features - if we made clients query for the > availability of the features they're using, you could version the > features independently. > > For example, if we decide we must make an incompatible change to some > obscure feature, wouldn't it be nice to version the feature rather > than bump the major version of the API. > > Also, it allows the API to have optional features that not all > service providers support.
+1 Linear versioning is of very limited use. I'd rather query the API and get back some JSON that enumerates the extensions available -- including their major versions, which is really just part of their names -- and links to their root resources (what some might call 'endpoints'). This is kind of already done in the /extensions resource; it just needs to link to the actual endpoints. The place that it *is* appropriate to put an exact version of the software in use is the Server response header, for debugging; e.g., Server: Nova/1.4.2 and of course, if we want to list extensions, something like: Server: Nova/1.4.2 EC2plugin/3.0 MyFavouriteExtension/3.2.1 Again, this isn't for discovering server capabilities; really just debugging. Likewise, clients should be sending meaningful User-Agents, if they aren't already. While we're talking about versions -- I see that the 1.1 docs allow both URI and media type versioning. That makes me pretty uncomfortable, for a few reasons: * Having two ways to do it is duplication of effort / more opportunities for bugs * There isn't a 1:1 correspondence between URI versioning and media type versioning; for example, a new URI tree can introduce new resources, remove others, or drastically change the semantics of a resource itself. Media type versioning is limited to the semantics of the representation, not the behaviour of the resource. * Major versioning implies a change in core semantics, which is out of scope for media type versioning. I.e., if there's a backwards-incompatible change, it needs a new URI * Using conneg for versioning requires that the server send a Vary header, so that caches won't serve the wrong response to a client. That isn't being done now, AFAICT. This isn't to say that there isn't a place for media type versioning in the APIs, just that it fulfils a very different function (managing change in representation formats). Cheers, -- Mark Nottingham http://www.mnot.net/ _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
