Story #4308

[API] [SDKs] Enable API versioning

Added by Peter Amstutz over 6 years ago. Updated about 4 years ago.

Status:
Closed
Priority:
Normal
Assigned To:
-
Category:
API
Target version:
-
Start date:
Due date:
% Done:

0%

Estimated time:
Story points:
-

Description

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:
  1. 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').
  2. 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


Related issues

Related to Arvados - Story #3362: [SDKs] Notify user if client library version is much older than serverClosed

Copied to Arvados - Story #10849: [API] [SDKs] When client and server versions differ, the server must either implement the API the client expects, or return an error.New01/09/2017

History

#1 Updated by Peter Amstutz over 6 years ago

  • Description updated (diff)
  • Category set to API

#2 Updated by Brett Smith over 6 years ago

  • Subject changed from [API] [SDK] Enable API versioning to [API] [SDKs] Enable API versioning
  • Target version set to Arvados Future Sprints

#3 Updated by Tom Clegg about 4 years ago

  • Status changed from New to Closed

#4 Updated by Tom Morris about 4 years ago

  • Target version deleted (Arvados Future Sprints)

Also available in: Atom PDF