openstack team mailing list archive

[Mark Nottingham <mnot@xxxxxxxx>]

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@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp

--
Mark Nottingham   http://www.mnot.net/