Putting the version in the URI is a "variant" resource just like adding
.xml or .json . If you want the ability to get to a specific
representation in a browser (as opposed to a custom client) you can't
rely on content negotiation because browsers hard code their accepts clause.
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 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.
_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to : openstack@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack
More help : https://help.launchpad.net/ListHelp
