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
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