I'm struggling with the backward compatibility of a RESTful interface.
I can't find any documentation on the standard way to solving this. I
know that as long as you only extend the RESTful interface there is no
backward compatibility issue, but I don't believe that is a very
realistic situation (I refactor a lot). Say you want to change an
attribute's name, how would you solve this?
For the solution I've got the following assumptions:
- The interface version should not be placed in the URL (i.e.
www.mydomain.com/v2/books). The URL defines the resource, the
interface version is not part of the resource in my opinion.
- The interface version should not be placed in the parameters (i.e.
www.mydomain.com/books?version=2). This is an option, but it would
pollute my urls.
- Only the first interface version can be defaulted, because changing
the default will break existing client implementations using the
previous default. So this default is not really usefull in the long
run, since only version 1 can use it. But at least this would allow
people to leave out the interface version description, if they don't
have to be backward compatible.
I believe that an ideal solution to this would be to place the version
in the HTTP headers. Only there is no standard defined for it as far
as I can see. But it would be like the following:
POST www.mydomain.com/books HTTP/1.1
For the controller we could then apply a before_filter which rewrites
the param hash to the latest interface version (after determining the
used interface version from the header). The latest interface
definition is then used in the controller actions.
I think this can be quite clean.
Does anybody have know of a standard solution for this problem?