Understanding the Tenant Management API

StorageGRID Webscale provides a REST API for managing the tenant account.

Tenant Management API documentation

The Tenant Management API uses the Swagger open source API platform to provide the API documentation. Swagger allows both developers and non-developers to interact with the API in a user interface that illustrates how the API responds to parameters and options. This documentation assumes that you are familiar with standard web technologies and the JSON (JavaScript Object Notation) data format.

Attention: Any API operations you perform using the Swagger user interface are live operations. Be careful not to create, update, or delete configuration or other data by mistake.

You can access the Tenant Management API documentation by signing in to the Tenant Management Interface and selecting Help > API Docs in the web application header.
screenshot showing how to access the API Docs menu item

API

Each REST API command includes the API's URL, an HTTP action, any required or optional URL parameters, and an expected API response.

The Swagger user interface provides complete details and documentation for each API operation, as in the following example. To get information about a local tenant user, you would enter that user's unique name as the value for the shortName parameter and click Try it out.


screenshot showing the Swagger docs UI

The Tenant Management API includes the following sections:

Tenant Management API versioning

The Tenant 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 Tenant Management API that are backward incompatible bump the major version of the API. For example, an incompatible API change would bump the version from 1.1 to 2.0. Changes in the Tenant 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 would bump 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 Tenant 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 release.

Outdated requests are marked as deprecated in the following ways:
  • The response header is "Deprecated: true"
  • The JSON response body includes "deprecated": true

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/v2) or a header (Api-Version: 2). If you provide both values, the header value overrides the path value.

curl https://[IP-Address]/api/v2/org/config

curl -H "Api-Version: 2" https://[IP-Address]/api/org/config