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@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 > > -- 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
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
