Open Stack

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/