| Thread Previous • Date Previous • Date Next • Thread Next |
REST is media type centric and so I agree that the preferred way for a client to get a version it understands should be via content negotiation against unversioned permalinks. I recommend representations generally use unversioned URIs in most links for this purpose. I use rel=bookmark to explicitly mean the unversioned permalink of a resource. It's really easy to write a client this way: the client should look at the version info document and determine the media types the API requires and create client code for those media types and form a static accepts clause for all the media types it supports and navigate around the unversioned links.
Browsers can't do this, though. If that's all you do, a developer can't manually inspect payloads in a browser. The versioned variants exist mainly for this purpose. We should STRONGLY discourage clients from persisting versioned links as they will all break over the long haul if we EOL older versions of things.
Jorge & company have solved how to implement this easily using Repose. It basically rewrites requests, so the service only implements it one way, but you get both for free.
On 10/11/2011 08: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 identifierthat 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.
| Thread Previous • Date Previous • Date Next • Thread Next |
