On 10/12/2011 07:55 PM, Mark Nottingham wrote:What do you mean by "version N of the resource"? We version languages to describe things, not the things themselves. Usually the resources are real world instances in our business domain that only know their current real-world state. We come up with different recipes to project that state onto to a representation if it makes sense.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. The API may break backwards compatibility as a whole, but contain resources that continue to make sense. Breaking backwards compatibility does not require a burn-the-bridges break with the past. Here's an example: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. Lets say in v1 of my API I have servers and they have IPs . Resources are like so: http://cloud.net/servers/456 http://cloud.net/servers/456/ips http://cloud.net/ip/200.100.99.98 I realize I want to model multiple NICs and that a server's IPs aren't direct children of the server any more, but require their NIC: http://cloud.net/servers/456 http://cloud.net/servers/456/eth0/ips http://cloud.net/servers/456/eth1/ips http://cloud.net/ips/200.100.99.98 This breaks backwards compatibility of the API as servers with multiple NICs no longer honor the WADL template http://cloud.net/server/{server_number}/ips . Such servers would also only support the v2 media type app/vnd.server;version=2 at http://cloud.net/server/{server_number} as now we split the IP list up under each listed NIC .Note if I have a server with one NIC, it can continue to work fine with either v1 or v2. In these cases, the resource meaning of http://cloud.net/server/456 and http://cloud.net/ips/200.100.99.98 isn't version dependent. If a server 789 is a new multi-NIC server, an old v1 client would still see it listed at http://cloud.net/servers, but a GET against http://cloud.net/servers/789 that accepts only app/vnd.server;version=1 would have to get a 406 response and a choices document showing it only supports app/vnd.server;version=2. If this seems harsh, note that I can only get such a server if I'm using a multi-NIC aware v2 client to create/configure it. If server 876 is single NIC server, then it will work fine, yielding representations in either API version. I wish that HTML and browsers would let you specify the media type or accepts header with a link: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. <a href="" type="application/json">bar as json</a> This, combined with actually using status code 300 and agent-driven content negotiation by sending an html menu would be so much cleaner. |
_______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
