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
Note
A new authentication method is in use as of June 2020. Previous methods (under Deprecated Authentication) are now deprecated and will be removed in a future release.
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:
- Go to user settings.
- Click Access Tokens.
- Create a new one and add a descriptive name to it.
- Click Create; this will cause a new window to pop up to ask the user to confirm.
- Copy the
client_id
andapi_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
Note
This method of authentication is deprecated and will be removed in a future release. Please see Authentication above for the current authentication methods.
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
Note
This method is deprecated and will be removed in a future release.
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
Note
This method is deprecated and will be removed in a future release.
Note
Because there is now a new authentication method, all existing access_key
and access_secret
s are invalid. You will need to generate new API Tokens and update your clients accordingly.
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
Note
This section relates to the old authentication method which is deprecated and will be removed in a future release.
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.