Supported Swift API endpoints

StorageGRID Webscale supports the following Swift API endpoints: the info URL, the auth URL, and the storage URL.

info URL

You can determine the capabilities and limitations of the StorageGRID Webscale Swift implementation by issuing a GET request to the Swift base URL with the /info path.

https://FQDN | Node_IP:Swift_Port/info/
In the request:
  • FQDN is the fully qualified domain name.
  • Node_IP is the IP address for the Storage Node or the API Gateway Node on the StorageGRID Webscale network.

  • Swift_Port is the port number used for Swift API connections on the Storage Node or API Gateway Node.

For example, the following info URL would request information from a Storage Node with the IP address of 10.99.106.103 and using port 18083.
https://10.99.106.103:18083/info/

The response includes the capabilities of the Swift implementation as a JSON dictionary. A client tool can parse the JSON response to determine the capabilities of the implementation and use them as constraints for subsequent storage operations.

The StorageGRID Webscale implementation of Swift allows unauthenticated access to the info URL.

auth URL

A client can use the Swift auth URL to authenticate as a tenant account user.

https://FQDN | Node_IP:Swift_Port/auth/v1.0/     
You must provide the tenant account ID, user name, and password as parameters in the X-Auth-User and X-Auth-Key request headers, as follows:
X-Auth-User: Tenant_Account_ID:Username
X-Auth-Key: Password 
In the request headers:
  • Tenant_Account_ID is the account ID assigned by StorageGRID Webscale when the Swift tenant was created. This is the same tenant account ID used on the Tenant Manager sign-in page.

  • Username is the name of a tenant user that has been created in the Tenant Manager. This user must belong to a group that has the Administrator permission. The tenant's root user cannot be configured to use the Swift REST API.

    If Identity Federation is enabled for the tenant account, provide the username and password of the federated user from the LDAP server. Alternatively, provide the LDAP user's domain name. For example:
    X-Auth-User: Tenant_Account_ID:Username@Domain_Name
  • Password is the password for the tenant user. User passwords are created and managed in the Tenant Manager.

The response to a successful authentication request returns a storage URL and an auth token, as follows:

X-Storage-Url: https://FQDN | Node_IP:Swift_Port/v1/Tenant_Account_ID
X-Auth-Token: token
X-Storage-Token: token

By default, the token is valid for 24 hours from generation time.

Tokens are generated for a specific tenant account. A valid token for one account does not authorize a user to access another account.

storage URL

A client application can issue Swift REST API calls to perform supported account, container, and object operations against an API Gateway Node or Storage Node. Storage requests are addressed to the storage URL returned in the authentication response. The request must also include the X-Auth-Token header and value returned from the auth request.

https://FQDN | IP:Swift_Port/v1/Tenant_Account_ID
[/container][/object]
X-Auth-Token: token

Some storage response headers that contain usage statistics might not reflect accurate numbers for recently modified objects. It might take a few minutes for accurate numbers to appear in these headers.

The following response headers for account and container operations are examples of those that contain usage statistics: