openstack team mailing list archive

[Brian Waldon <brian.waldon@xxxxxxxxxxxxx>]

Your proposed solution to my example implies we would have to support *all* major versions of the compute API to some degree. I absolutely don't want to track redirects from v1 to v2 to v3 to v4 when we are developing v5. That seems like a painful thing to have to do. We also couldn't guarantee that the entity returned from the latest version (like v5) looks anything like that defined in the requested version (like v1).

On Oct 11, 2011, at 10:46 AM, George Reese wrote:

> In the example you use, the proper HTTP behavior is for the API should allow for a HTTP 302 response and clients should follow the permanent move. This provides both a persistent reference based on the URI and a way to handle the alteration of URI structure.
> 
> -George
> 
> On Oct 11, 2011, at 2:56 PM, Brian Waldon wrote:
> 
>> I'm not sure I agree with that. A URI should be a persistent reference to a resource within the context of a major version of an API. Between major versions, the URI structure can change completely (for example /servers -> /instances), destroying your persistent reference.
>> 
>> Additionally, if we only support requests within the context of the latest minor version of an API, the major version is the only piece of information that matters. The mechanism for versioning through content types will only be valid within a single major version, as I do not want to define a spec that resides above all major versions of our api.
>> 
>> Waldon
>> 
>> 
>> On Oct 11, 2011, at 9: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@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
>>> 
>>> This email may include confidential information. If you received it in error, please delete it.
>> 
>> 
>> 
>> --------------------------------------
>> Brian Waldon
>> Cloud Software Developer
>> Rackspace Hosting
>> 
>> 
> 
> --
> 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
> 
> This email may include confidential information. If you received it in error, please delete it.



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