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