On 12/10/2011, at 6:10 PM, Bryan Taylor wrote: > On 10/11/2011 09:02 PM, Mark Nottingham wrote: >> 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). > 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.
I think we agree here. I'm not advocating one or the other as a single solution -- I'm saying that doing a purely mechanical transformation between URI versioning and media type versioning (as the 1.1 docs seem to indicate) is worse than useless, it's actively harmful. > 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. Agreed; see other thread. > The duplication of effort can be solved by having an intermediary do the > translation. Repose already does this. That's where there be dragons. Inferring that the user wants to go to version N of the resource because they request version M of the representation conflates format versioning with API versioning. They are not the same. > 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 . Why? If you wipe the slate clean and start a /v2 API, the whole idea is that it's not backwards-compatible with v1. Predicating it on v1 just ties your hands. > 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. *Shrug* I'm not really interested in RESTfulness for its own sake, so that's OK. > 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 . See above. > 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 -- Mark Nottingham http://www.mnot.net/ _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
