Story #4308
Updated by Peter Amstutz about 10 years ago
Increasingly we're running into the problem where the SDK is written against an older version of the API that turns out to be incompatible. Because we have not been versioning the API the (everything is just arvados/v1/*) there is no way to offer different behavior to different client versions or to detect if a client is out of date and likely to fail.
There's a couple of options to go about this:
# On API server, parameterize the version portion of the namespace, so the routes look like @/arvados/:version/:controller@ (it's unclear if there's an easy way to do this that doesn't involve rewriting all the routes with 'get' and 'match' instead of 'resource').
# Require a version header with every request.
For #2, The 'v1' portion of the arvados API path becomes legacy that we can transition away from. If we start routing directly under /arvados, such as /arvados/pipeline_instances, etc this has the benefit of providing stable URIs to Arvados objects which may be desirable for future federation, metadata frameworks, etc.
Discussion: https://stackoverflow.com/questions/9627546/api-versioning-for-rails-routes