openstack team mailing list archive

[Bryan Taylor <btaylor@xxxxxxxxxxxxx>]

On 10/24/2011 11:20 PM, Mark Nottingham wrote: 
> tl;dr
Much omitted, since it's long... I agree strongly with 98% of what you are saying.

I'll focus on the variants here. I'd rather just get rid of them.

> GET /servers.v1.json
vs
> http://api.example.com/v1/foo

I agree with you that the latter violates some RESTful ideals, but so does the former. Whether the "v1" comes with dots or slashes or at the root or leaf of the hierarchy doesn't really change the fact that you are polluting your resource namespace with representation specific information. The same goes for .json: internet standard vs openstack representation doesn't matter - it's still representation information. 

You could argue the /v1 doesn't belong at the top of the resource tree, but this removes ambiguity about the ordering. eg: /servers.json.v1 vs /servers.v1.json. To be truly RESTful at the level of the Fielding article (which I actually think is the best description of HATEOAS there is) you shouldn't have these variants at all.  I worry about us trying to put lipstick on the pig -- all these variants are a crummy compromise to work around broken browsers that do allow changing the accepts header. 

I floated the idea a while back that we get rid of variants altogether and instead use an HTML representation to offer the user a choice of how to view the information that includes <pre> elements with JSON and XML formatted text. It could also have a nice human readable representation so that users could directly navigate around in the browser. Remember that the only use case justifying variants are human developers who want to see what the JSON or XML will look like.

If we do this, then we have GET /server/1234 and everything is clean. Jorge pointed out one slight problem with this: <pre> can only display textual representations. So no pdfs or excel spreadsheets without conneg. If we could live with this, getting rid of the variants altogether seems like a win.