Skip to main content

Grid Management API versioning

Contributors
PDFs

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

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

https://hostname_or_ip_address/api/v4/authorize

The major version of the API is bumped when changes are made that are not compatible with older versions. The minor version of the API is bumped when changes are made that are compatible with older versions. Compatible changes include the addition of new endpoints or new properties.

The following example illustrates how the API version is bumped based on the type of changes made.

Type of change to API Old version New version

Compatible with older versions

2.1

2.2

Not compatible with older versions

2.1

3.0

3.0

4.0

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

Note You can configure the supported versions. See the config section of the Swagger API documentation for the Grid Management API for more information. You should deactivate support for the older version after updating all API clients to use the newer version.

Outdated requests are marked as deprecated in the following ways:

  • The response header is "Deprecated: true"

  • The JSON response body includes "deprecated": true

  • A deprecated warning is added to nms.log. For example:

    Received call to deprecated v2 API at POST "/api/v2/authorize"

Determine which API versions are supported in the current release

Use the GET /versions API request to return a list of the supported API major versions. This request is located in the config section of the Swagger API documentation.

GET https://{{IP-Address}}/api/versions
{
  "responseTime": "2023-06-27T22:13:50.750Z",
  "status": "success",
  "apiVersion": "4.0",
  "data": [
    2,
    3,
    4
  ]
}

Specify an API version for a request

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

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

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