Following is a summary of the Cloud Volumes REST API v2 and its uses.

Schema

The service only supports HTTPS requests and all data exchanged with request or response bodies uses JSON format. The base URL is https://cloudvolumes.hpe.com/api/v2.

Requests require an Accept header set to application/json. POST and PATCH requests require a Content-Type header of application/json.

Responses

All responses return a data field which contains the id, type, attributes and links for a given resource. All resource-specific fields are added as part of attributes, with blanks or nulls omitted.

All timestamps are from the UTC timezone and formatted in POSIX or epoch time: a positive integer accounting for the number of seconds elapsed since 00:00:00 UTC.

{
    "data": {
        "attributes": {
            ...
        },
        "id": 1,
        "type": "resource_type",
        "links": {
            ...
        }
    }
}

Resources

As expected, each set of endpoints interacts with a given type of resource. All responses identify the resource they refer to - as well as any related or embedded resources - with the type field.

Resource Lists

Any endpoints that return a list of resources will usually do so with a subset of their attributes. The list part of a data field and its items may be limited based on the authorization available in the current session.

{
    "data": [
        {
            "attributes": {
                ...
            },
            "id": 1,
            "type": "resource_type",
            "links": {
                ...
            }
        },
        ...
    }
}

Parameters

Most of the API methods take optional parameters, while some have required parameters.

For GET requests, if not specified in the path of the requested resource, they should be included as part of the query string:

GET /cloud_volumes?fields=name,user

All POST and PATCH requests also use parameters sent as part of the body. They must be in JSON format. Parameters must also be wrapped under a data attribute for all endpoints except authorization, the latter going to a third-party service. Therefore, when issuing these requests, make sure to include a content-type header of application/json and to wrap parameters in a data attribute, as shown in the following example:

{
    "data": {
        "parameter1": "string_param1",
        "parameter2": 2
    }
}

Versioning

While these documents describe version 2 of the API, it's important to note that other iterations are made available by changing the version string in the base URL.

Service Endpoint

Issuing a GET to the service endpoint is a good way of verifying the API is up and that you're talking to the correct version.

GET /service
{
    "data": {
        "service": "HPE CloudVolumes REST API",
        "version": "2.0.0"
    }
}

Authentication

User Authentication

User authentication is supported through interactive login only through the UI at https://console.cloudvolumes.hpe.com/login.

The access_token returned to the browser after a successful login can be used on an ad-hoc basis to make subsequent API requests. For programmatic use, users should generate an API Token instead.

API Token

Requesting an API Token

Users can generate multiple long-lived API Tokens that are tied to their user:

1. Go to user settings.
2. Click Access Tokens.
3. Create a new one and add a descriptive name to it.
4. Click Create; this will cause a new window to pop up to ask the user to confirm.
5. Copy the client_id and api_token.

Keep the api_token safe as it is a credential with the same level of authorization as your username and password.

Best practice is to create one per device so you can disable them individually if the device is compromised or lost.

Using an API Token

POST https://login.cloudvolumes.hpe.com/oauth/token
Content-Type: application/json
Accept: application/json
{
  "grant_type": "refresh_token",
  "client_id": "<client_id>",
  "refresh_token": "<api_token>"
}

where the values for the fields in <> are provided by the user.

If successful, you will get a 200 response with the following json body:

{
  "access_token": "eyJ...39g",
  "scope": "offline_access",
  "expires_in": 86400,
  "token_type": "Bearer",
  "expires_at": 1584181812
}

Extract the access_token string and add it (without quotes) as a Bearer Authorization header to subsequent cloudvolumes API requests: Authorization: Bearer <access_token>

The access token will expire after 12 hours, at which point you will need to request a fresh access_token by repeating the Refresh Token grant request. Many OAuth 2.0 client libraries handle acquiring a new access_token automatically.

The access_token and refresh_token/api_token should be secured as they allow access to the system as the user that requested the api_token.

Deprecated Authentication

There are two authentication mechanisms available with the REST API. One that requires user credentials (email / password) and one that uses access keys and secrets.

To authenticate, issue a POST to https://cloudvolumes.hpe.com/auth/login with a content-type header of appplication/json and a body that includes the credentials you wish to use (more info below). This will give you an authorization token to use in subsequent API requests.

Deprecated User Authentication

POST https://cloudvolumes.hpe.com/auth/login
Content-Type: application/json
Accept: application/json
{
    "email": "email@example.com",
    "password": "your_password"
}

Deprecated Access Keys Authentication

POST https://cloudvolumes.hpe.com/auth/login
Content-Type: application/json
Accept: application/json
{
    "access_key": "your_access_key",
    "access_secret": "your_access_secret"
}

Deprecated Response

Logins that are Successful return with a 200 status code and provide an authorization token to use in future requests. This token will expire, at which point you start receiving 401 responses. If you wish to continue using the API, you have to authenticate once again and use the new token from this point forward.

{
    "token": "your_new_token"
}

Failed attempts will return 401 Unauthorized.

Authorization Token

After obtaining a valid authorization token through the login process described previously, subsequent API requests require this token in an Authorization header. We prefer to use Bearer auth, so the header is just the access_token or token field as returned by the login step. For example:

GET https://cloudvolumes.hpe.com/api/v2/cloud_volumes
Authorization: Bearer eyJ...39g
Accept: application/json

Errors

All error objects return with the HTTP status code that best identifies the situation. The responses are also in JSON format and provide more details through these fields:

• code - string that identifies the error code (NotFound, ResourceNotFound, ResourceConflict, etc.).
• title - short user-readable string for the error code.
• detail - longer string with more information on what went wrong.
• status - the HTTP status code for this error.

Example:

{
    "title": "Not Found",
    "code": "NotFound",
    "detail": "The requested URL was not found on the server.  If you entered the URL manually please check your spelling and try again.",
    "status": 404
}

Typically you'll find the following status codes (more details per endpoint provided in the reference doc):

• 400 for malformed requests.
• 404 identifies unknown URLs or resources.
• 409 is used when running into a conflict that prevents the requested action. A good example is duplicate names.
• 422 when request parameters are invalid.

Rate Limiting

Various sections of the API are rate limited. A good example is the login endpoint, which will return a 429 HTTP status code if you've exceeded the number of requests allowed. If you encounter this situation, it's sufficient to wait a short amount of time before issuing the request again.