Open Stack

Putting the version in the URI is a "variant" resource just like adding 
.xml or .json . If you want the ability to get to a specific 
representation in a browser (as opposed to a custom client) you can't 
rely on content negotiation because browsers hard code their accepts clause.

REST is media type centric and so I agree that the preferred way for a 
client to get a version it understands should be via content negotiation 
against unversioned permalinks. I recommend representations generally 
use unversioned URIs in most links for this purpose. I use rel=bookmark 
to explicitly mean the unversioned permalink of a resource. It's really 
easy to write a client this way: the client should look at the version 
info document and determine the media types the API requires and create 
client code for those media types and form a static accepts clause for 
all the media types it supports and navigate around the unversioned links.

Browsers can't do this, though. If that's all you do, a developer can't 
manually inspect payloads in a browser. The versioned variants exist 
mainly for this purpose. We should STRONGLY discourage clients from 
persisting versioned links as they will all break over the long haul if 
we EOL older versions of things.

Jorge & company have solved how to implement this easily using Repose. 
It basically rewrites requests, so the service only implements it one 
way, but you get both for free.

On 10/11/2011 08:14 AM, George Reese wrote:
> 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 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
>
> --
> George Reese - Chief Technology Officer, enStratus
> e: george.reese at enstratus.com    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
>

This email may include confidential information. If you received it in error, please delete it.