On 10/11/2011 09:02 PM, Mark Nottingham wrote: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.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). 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. The duplication of effort can be solved by having an intermediary do the translation. Repose already does this. 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 . 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. |
_______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
