<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
<title></title>
</head>
<body bgcolor="#ffffff" text="#000000">
On 10/11/2011 09:02 PM, Mark Nottingham wrote:<br>
<blockquote cite="mid:1EF523A8-A4F5-4D71-89BA-DA3B8F98919D@mnot.net"
type="cite">
<pre wrap="">While we're talking about versions -- I see that the 1.1 docs allow both URI and media type versioning. That makes me pretty uncomfortable, for a few reasons:
* Having two ways to do it is duplication of effort / more opportunities for bugs
* There isn't a 1:1 correspondence between URI versioning and media type versioning; for example, a new URI tree can introduce new resources, remove others, or drastically change the semantics of a resource itself. Media type versioning is limited to the semantics of the representation, not the behaviour of the resource.
* Major versioning implies a change in core semantics, which is out of scope for media type versioning. I.e., if there's a backwards-incompatible change, it needs a new URI
* Using conneg for versioning requires that the server send a Vary header, so that caches won't serve the wrong response to a client. That isn't being done now, AFAICT.
This isn't to say that there isn't a place for media type versioning in the APIs, just that it fulfils a very different function (managing change in representation formats).
</pre>
</blockquote>
<small>Your points are mostly valid, but I think this is a case of
democracy being a terrible form of government, except for all the
others. Versioning purely on URIs sucks because there are no
permalinks and a client can't tell that /v1/foo and /v2/foo are
related. Versioning purely by content negotiation sucks because
you lose the ability of devs and customers to examine
representations in browsers. <br>
<br>
</small><small>I think ulitimatley if you do HATEOAS right, a client
never couples to your URI structure and so there's no such thing
as a backwards compatability breaking change of it. The URI
structure trees defined by a WADL are somewhat of an illusion. The
client sees one resource at a time and doesn't care if their URIs
obey a structure formula or not. The client navigates across an
arbitrary collection of resources each with an opaque URIs. <br>
<br>
</small><small>The duplication of effort can be solved by having an
intermediary do the translation. Repose already does this.<br>
<br>
We deal with the correspondence between versioned URIs and media
types by adopting a single structure rule that is non-RESTful:
/v1/foo and /v2/foo are implicitly understood to be variants of
/foo . This is similar to /bar.xml and /bar.json being implicitly
related to /bar . That's not RESTful either, but if you ever want
to see the JSON in a browser, you live with it. With this rule,
/foo supplies the union of media types supported by /v1/foo and
/v2/foo. Adding or removing resources translates into one of
/v1/foo or /v2/foo not existing. We disallow drastic changes in
what /foo means from v1 to v2. Similarly, /bar.xml should report
the same story as /bar.json because they implicitly track /bar .<br>
<br>
The prefered way for coded clients to use the APIs should be to do
conneg on unversioned permalinks. We probably should use a Vary
header, though until actually have v2's we won't get collisions.<br>
<br>
<br>
<br>
</small>
</body>
</html>