Grid Management API versioning

The Grid Management API uses versioning to support non-disruptive upgrades.

For example, this Request URL specifies version 2 of the API.

https://hostname_or_ip_address/api/v2/authorize

Changes in the Grid Management API that are backward incompatible bump the major version of the API. For example, an incompatible API change bumps the version from 1.1 to 2.0. Changes in the Grid Management API that are backward compatible bump the minor version instead. Backward-compatible changes include the addition of new endpoints or new properties. For example, a compatible API change bumps the version from 1.0 to 1.1.

When you install StorageGRID Webscale software for the first time, only the most recent version of the Grid Management API is enabled. However, when you upgrade to a new major version of StorageGRID Webscale, you continue to have access to the older API version for at least one major StorageGRID Webscale release.

Note: You can use the Grid Management API to configure the supported versions. See the “config” section of the Swagger API documentation for more information. You should deactivate support for the older version after updating all Grid Management API clients to use the newer version.
Outdated requests are marked as deprecated in the following ways:

Determining which API versions are supported in the current release

Use the following API request to return a list of the supported API major versions:
GET https://{{IP-Address}}/api/versions
{
    "responseTime": "2016-10-03T14:49:16.587Z",
    "status": "success",
    "apiVersion": "2.0",
    "data": [
        1,
        2
    ]
}

Specifying an API version for a request

You can specify the API version using a path parameter (/api/v1) or a header (Api-Version: 2). If you provide both values, the header value overrides the path value.

curl https://[IP-Address]/api/v2/grid/accounts

curl -H "Api-Version: 2" https://[IP-Address]/api/grid/accounts