Open Stack

On 10/11/2011 12:26 AM, Mark Nottingham wrote:
> Where would these versions show up? In URLs? In documentation? In
> response payloads?
> 
> If they show up in URLs, then every backwards-compatible change would
> be made into a backwards-incompatible change. E.g., if you had
> 
> http://www.example.com/v1.2.3/foo
> 
> as a resource, and adding a new resource .../bar bumps it to v1.2.4,
> then that backwards-compatible change (because it doesn't break old
> clients) now causes everybody to break.

Right. This is a trap to be avoided.
 
> The only sensible thing to put in URIs is a major version identifier
that indicates backwards-incompatible changes (i.e., the slate is wiped
clean, it's a different URL tree). E.g.,
> 
> http://www.example.com/v1/
> 
> Of course, that can be any arbitrary string, whether it be "v1" or
> "v1.1" or "essex". However, putting "v1.1" in there is going to confuse
> people, because most people believe that a minor release is, by nature,
> backwards compatible.

I like just plain old v1 as it's short and sweet. 

> If we want to just use them in documentation, there's no harm, of
> course. Likewise, the client could query the server to find out what it
> supports, but something more descriptive than a linear version number
> would be useful; e.g., some sort of linked capability catalogue format.

We are usually putting a version info resource at the version root, eg:
http://www.example.com/v1/

See here for how compute is doing it:
<http://docs.openstack.org/trunk/openstack-compute/developer/openstack-compute-api-1.0/content/ch03s09.html>

Unfortunately the example uses "v1.0" and is confusing as you noted above.

An idea I've dabbled with is putting the major and minor version number 
in the WADL filename. It'd be a good addition to WADL to allow it to express what
version it is in its conent.