Open Stack

I agree only the major version should be in the URL, and the major version
must be bumped if any API is changed such that the 'API contract' with existing clients
is broken somehow.  (Standard 'old manager/new agent' stuff.)

Traditionally, the software release version IDs need to be precise,
so when developers get a bug report, they know exactly what software
the customer is using.  Knowing just the API version in use is not good enough.


Andy

-----Original Message-----
From: openstack-bounces+biermana=brocade.com at lists.launchpad.net [mailto:openstack-bounces+biermana=brocade.com at lists.launchpad.net] On Behalf Of Brian Waldon
Sent: Tuesday, October 11, 2011 5:40 AM
To: Bryan Taylor
Cc: openstack at lists.launchpad.net
Subject: Re: [Openstack] OpenStack API Versioning Conventions

I'm all for exposing only the major version in the URI (/v1). We have fallen into a trap with v1.0 and v1.1 as they are not backckwards-compatible specs while their versioning implies they are. I think we can have a whole separate discussion on how to solve that problem, so like I said earlier, I would like to get buy-in on my original proposal before we move on to spec-specific details.

Thanks for the great input, guys!

Waldon


On Oct 11, 2011, at 2:12 AM, Bryan Taylor wrote:

> 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.
> 
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack at lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
> This email may include confidential information. If you received it in error, please delete it.
> 



--------------------------------------
Brian Waldon
Cloud Software Developer
Rackspace Hosting



_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to     : openstack at lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help   : https://help.launchpad.net/ListHelp