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

Almost all POST and PATCH requests also use parameters sent as part of the body. These must be in JSON format and wrapped by a data parameter. When issuing these requests, make sure to include a content-type header of application/json

{
    "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

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.

User Authentication

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

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"
}

Generating Access Key and Secret

Clicking the "Generate Secret" button in the Account section of the portal interface will create a new access key and secret for the current logged-in user. The secret is only visible once after clicking the button, so please take note of it for future use.

Response

Successful logins 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 use Basic auth, so the header is a base64 encoded string of username:token or access_key:token. For example: 

GET https://cloudvolumes.hpe.com/api/v2/cloud_volumes
Authorization: Basic bmN2YWRtaW5AbmltY_SNIP_fYmpnc3VPaw==
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.