openstack team mailing list archive

[George Reese <george.reese@xxxxxxxxxxxxx>]

Versioning should not be included in the URI. It belongs in the headers. A URI should be a persistent reference to a resource. As such, versioning always breaks that persistent reference.

-George

On Oct 11, 2011, at 1:40 PM, Brian Waldon wrote:

> 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
> 
> 
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp

--
George Reese - Chief Technology Officer, enStratus
e: george.reese@xxxxxxxxxxxxx    t: @GeorgeReese    p: +1.207.956.0217    f: +1.612.338.5041
enStratus: Governance for Public, Private, and Hybrid Clouds - @enStratus - http://www.enstratus.com
To schedule a meeting with me: http://tungle.me/GeorgeReese

Attachment: smime.p7s
Description: S/MIME cryptographic signature