Understanding the Tenant Management API

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.

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.

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.

The Tenant Management API includes the following sections:

• account – Operations on the current tenant account, including getting storage usage information.

• auth – Operations to perform user session authentication.

  The Tenant Management API supports the Bearer Token Authentication Scheme. For a tenant login, you provide a username, password, and accountId in the JSON body of the authentication request (that is, POST /api/v2/authorize). If the user is successfully authenticated, a security token is returned. This token must be provided in the header of subsequent API requests ("Authorization: Bearer token").

  See "How to protect against Cross-Site Request Forgery" for information on improving authentication security.

• config – Operations related to the product release and versions of the Tenant Management API. You can list the product release version and the major versions of the API supported by that release.

• containers – Operations on S3 buckets or Swift containers. Includes consistency level settings for S3 buckets and Swift containers. S3 buckets also include updates to last access time for objects, and configuration operations for platform services: CloudMirror replication, notifications, and search integration (metadata-notification).

• deactivated-features – Operations to view features that might have been deactivated.

• endpoints – Operations to manage an endpoint. Endpoints allow an S3 bucket to use an external service for StorageGRID Webscale CloudMirror replication, notifications, or search integration.

• groups – Operations to manage local tenant groups and to retrieve federated tenant groups from an external identity source.

• identity-source – Operations to configure an external identity source and to manually synchronize federated group and user information.

• s3 – Operations to manage S3 access keys for tenant users.

• users – Operations to view and manage tenant users.

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.

Determining which API versions are supported in the current release

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