Idea #10849
Updated by Tom Clegg almost 8 years ago
h3. Background
After an upgrade, an API server will receive some requests that were intended for an older version.
* Some nodes have older SDK code installed, because the API server gets upgraded first.
* Some nodes have older SDK code installed, because they are not covered by the cluster upgrade procedure (e.g., users' workstations).
* Even on nodes with the most current SDK, some processes are still using the old SDK code and discovery document, because they started before the API server was upgraded.
Currently, the discovery document provides an API "revision" which clients can check _before_ making API calls. However:
* Our testing framework does not remind/force us to update this API version when the API changes (it has changed only twice since being introduced as "20121015", and is now "20131114").
* SDKs do not check it.
* Even if SDKs checked it, an API-side check would still be necessary to cover the cases where the API server is upgraded between discovery document retrieval and API request.
h3. Requirements
In the discovery document, the API server should provide a list of supported API versions, sorted with preferred (more recent) versions first. When a schema or API change breaks support for an older version, the old version should be dropped from the list.
Before making an API request, a client should check the list of supported versions (in the discovery doc) and choose which version to use. Depending on the client, this could be the latest advertised version, or a specific version the client was developed for.
When making an API request, a client should provide the expected API version in a request header "x-arvados-api-version" or (if the client has trouble adding http headers) a form value or query parameter "api_version".
When receiving an API request, the API server should check the client-supplied version string against the list of supported versions, and respond 4xx if the requested version is not supported.
h3. Future work
When forwarding an API request, the API gateway should check the requested API version and forward the request to an appropriate API server or version-translating proxy server.
Build/test tooling should try to detect (and prevent) API changes that slip through without updating the API version.