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@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@lists.launchpad.net >> Unsubscribe : https://launchpad.net/~openstack >> More help : https://help.launchpad.net/ListHelp > > -- > George Reese - Chief Technology Officer, enStratus > e: george.re...@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. -------------------------------------- Brian Waldon Cloud Software Developer Rackspace Hosting _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
