openstack team mailing list archive

[Brian Waldon <brian.waldon@xxxxxxxxxxxxx>]

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@xxxxxxxxxxxxxxxxxxx
> 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