REST API Reference
Your system provides a RESTful API that you can use for writing applications that manage the system. Anything you can do in the System Management application can also be performed using the REST API.
Information is available about the APIs in two places:
- For information about System Management application APIs, see the topics in this document.
- For information about Object Storage Management and S3 APIs, see the Help for the Object Storage Management application.
Input and output formats
The REST API accepts and returns JSON.
Access and authentication
To use the REST API, you need a user account that has permission to perform the actions you want.
Once you have a user account, you need to request an authentication token from the system. To do this, you send an HTTP POST request to the /auth/oauth endpoint.
When you generate a new access token, a refresh token also gets generated automatically.
Here's an example using the cURL command-line tool:
curl -ik -X POST https://mysystem.example.com:8000/auth/oauth/ \
-d grant_type=password \
-d username=user1 \
-d password=password1 \
-d scope=* \
-d client_secret=my-client \
-d client_id=my-client \
-d realm=marketingUsers
In response to this request, you receive a JSON response body containing an access_token field. The value for this field is your token. For example:
{"access_token" : "eyJr287bjle..."
- To get a list of security realms for the system, send an HTTP GET request to the /setup endpoint. For example, to do this with cURL:
curl -k -X GET --header 'Accept: application/json' 'https://mysystem.example.com:<admin-app-port>/api/admin/setup' - To get an access token for the local admin user account, you can omit the realm option for the request, or specify a realm value of Local.
You need to specify your access token as part of all REST API requests that you make. You do this by submitting an Authorization header along with your request. Here's an example that uses cURL:
curl -X GET --header "Accept:application/json" https://mysystem.example.com:<admin-app-port>
/api/admin/instances --header "Authorization: Bearer eyJr287bjle..."
You can use the REST API to change your system's password using the following cURL command.
$1=<server-name>
$2=<current-password>
$3=<new-password>
TOKEN=$(curl -ik -X POST https://$1.mysystem.com:8000/auth/oauth/ -d grant_type=password
-d username=admin -d password=$2 -d scope=* -d client_secret=hci-client -d client_id=hci-client
-d realm=local 2>&1 | grep access_token | awk -F: '{print $2}' | awk -F\" '{print $2}')
curl -v -X POST --header 'Content-Type: application/json' --header "Authorization: Bearer $TOKEN"
https://$1.mysystem.com:8000/api/admin/setup/password -d '{"password": "'"$3"'"}'
Viewing and using REST API methods
Your system provides web-based documentation pages where you can view all supported REST API methods, including the request bodies, request URLs, response bodies, and return codes for each. You can also use these pages to run each REST API method.
Viewing the API documentationTo view the REST API documentation, in the System Management application, click on the user icon (
). Then click on REST API - Admin.
To view the HCP for cloud scale API documentation, click REST API in the Object Storage Management application.
Making requestsYou can use the REST API documentation pages to experiment with the REST API.
Procedure
Click on the row for the method you want.
If the method you want requires that you specify a UUID:
Click on the row for the GET method for the resource type that you want.
Click on the Try it Out! button.
In the JSON response body, copy the value for the uuid field for the resource that you want.
NoteIf you specify UUIDs when creating resources, the UUIDs are ignored.
If the method you want requires that you specify a request body:
In the Parameters section, under Model Schema, click inside the JSON text box.
The JSON text is added to the Value field.
Edit the JSON in the Value field.
NoteSome methods may require other information in addition to or instead of UUIDs or JSON-formatted text. Some require particular string values or require that you browse for and select a file to upload.
Click on the Try it out! button.
Error responses
When an API request fails, the API returns:
- An HTTP status code
- Conditionally, a system-specific error code
- A JSON-formatted error response body
This table describes the typical reasons why these HTTP status codes are returned. For information on the status codes for a particular method, view the system REST API web interface.
| Status code | Description |
| 400 (Bad Request) |
The request body contains one or more of these:
If the request includes a UUID, the UUID may be invalidly formatted. |
| 403 (Forbidden) | You do not have permission to perform the request. |
| 404 (File not found) | The resource you are trying to retrieve or edit cannot be found. |
| 409 (Conflict) | The resource you are trying to create already exists. |
| 500 (Server Error) | The system experienced an error. |
Some API requests return system-specific error codes in addition to an HTTP status code.
These error codes are listed in the errorCodes field in the JSON response
body. This table describes these error codes.
| Error code | Description |
| 4000 | SSL certificate not trusted. |
REST API error responses have this format:
{
"statusCode": <HTTP-status-code>,
"errorCode": <system-specific-error-code>,
"errorMessage": <message>,
"errorProperties": [
{
"name": <error-property>,
"message": <error-property-message>
}
]
}