Introducing Hitachi Content Platform for cloud scale

Last updated
Save as PDF

Hitachi Content Platform for cloud scale (HCP for cloud scale) is a software-defined object storage solution that is based on a massively parallel microservice architecture and is compatible with the Amazon S3 application programming interface (API).

HCP for cloud scale is especially well suited to service applications requiring high bandwidth and compatibility with the Amazon S3 API.

HCP for cloud scale has the ability to federate S3-compatible storage from virtually any private or public source, and present the combined capacity in a single, centrally managed, global namespace.

You can install HCP for cloud scale on any server, in the cloud or on premise, that supports the minimum requirements.

HCP for cloud scale lets you manage and scale storage components. You can add storage components, monitor their states, and take them online or offline for maintenance and repair. The HCP for cloud scale system includes functions to send notification of alerts, track and monitor throughput and performance, and trace actions through the system.

Getting started with the management APIs

HCP for cloud scale includes RESTful HTTP management application programming interfaces (MAPIs) for the Object Storage Management application and the System Management application. These MAPIs are separate and use separate ports.

System Management

You can execute all functions supported in the System Management application using MAPI methods. The System Management methods are served by the Admin service from any HCP for cloud scale node.

All URLs for the System Management MAPI methods have the following base, or root, uniform resource identifier (URI):

https://hcpcs_cluster:8000/api/admin/

The System Management MAPI is described in Swagger, available from the System Management user interface. Those methods are not described in this document.

Object Storage Management

You can execute all functions supported in the Object Storage Management application and the S3 Console application using MAPI methods. The Object Storage Management management API (MAPI) supports management of the following:

Storage components and Amazon Simple Storage Service (Amazon S3) settings
Storage component encryption
KMIP (Key Management Interoperability Protocol) servers
Administrative resources such as serial numbers and system events
User resources such as S3 user credentials and OAuth tokens
Public information such as available public ports

The Object Storage Management MAPI methods are served by the MAPI Gateway service from any HCP for cloud scale node.

All URLs for the Object Storage Management MAPI methods have the following base, or root, uniform resource identifier (URI):

https://hcpcs_cluster:9099/mapi/v1/

The Object Storage Management MAPI is described in the Management API Reference. It is also described in Swagger, available from the Object Storage Management user interface.

Input and output formats

The API accepts and returns JSON.

The REST API accepts and returns JavaScript Object Notation (JSON). It does not support HTTPS 1.0 requests; all HTTPS 1.0 requests are denied. When the body of the request has contents, the MAPI accepts and returns JSON; when the body is empty, JSON format is unnecessary.

Access and authentication

To use the Object Storage Management or System Management MAPIs, you need a user account that has permission to perform the actions you want.

Requesting an access token

After you have a user account, you must request an authentication token from the system. To do this, you send an HTTP POST request to the method /auth/oauth.

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-secret \
-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 the token. For example:

{
"access_token": "eyJr287bjle..."
"expires_in": 7200
}

Note

To get a list of security realms for the system, send an HTTP GET request to the method /setup. For example, to do this with cURL:
```
curl -k -X GET --header 'Accept: application/json' \ 
'https://mysystem.example.com:8000/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.

Submitting the access token

You must specify the access token as part of all REST API requests that you make. You do this by submitting an Authorization header along with the request. Here's an example that uses cURL:

curl -X GET --header "Accept:application/json" \
https://mysystem.example.com:8000/api/admin/instances \
--header "Authorization: Bearer eyJr287bjle..."

Changing a password

You can use the MAPI to change the system's password using the following cURL commands, where $1=server_name, $2=current_password, and $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=client-secret -d client_id=client-id \
-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"'"}'

Requesting and submitting a CSRF token

To protect against cross-site-request forgery, the Object Storage Management MAPI requires an XSRF token and a Vert.x web session token in all requests. A MAPI method is provided to return the tokens in cookies for use in subsequent MAPI calls.

The Object Storage Management MAPI requires you to pass the XSRF token in the request header, and the XSRF token and Vert.x web session information as a cookie, within each request. If you do not use the tokens in a request, it will fail with a 401 (invalid) error.

TipThe XSRF token has a limited lifetime, so it's best to obtain a fresh token before issuing every group of requests.

To obtain the token and session information and pass them as part of a request:

Procedure

Use the MAPI method csrf to obtain the XSRF token and Vert.x web session information:
```
GET https://10.10.24.195:9099/mapi/v1/csrf
```
The XSRF token is returned as a cookie named XSRF-TOKEN and the Vert.x session token is returned as a cookie named vertx-web.session.

Next steps

Use the cookies in subsequent requests.

This example includes a set of commands that does the following:

Calls the MAPI method csrf and stores the response in a variable named cookieResponse
Finds the XSRF-TOKEN key string in the value stored in cookieResponse, extracts the value for that key, and stores it in a variable named xsrf
Finds the vertx-web.session key string in the value stored in cookieResponse, extracts the value for that key, and stores it in a variable named vertx
Stores the extracted XSRF and Vert.x tokens in a cookie named cookie
Passes the XSRF token and the cookie as part of a request to obtain S3 authorization, and saves the results in a variable named token

echo "Generating credentials for ${user}"
cookieResponse=`curl -s -kc - https://${cluster}:9099/mapi/v1/csrf`
xsrf=`echo "${cookieResponse}" | grep XSRF-TOKEN | cut -d$'\t' -f 7`
vertx=`echo "${cookieResponse}" | grep vertx-web.session | cut -d$'\t' -f 7`
cookie="XSRF-TOKEN=${xsrf}; vertx-web.session=${vertx}"
token=`curl -s -H "X-XSRF-TOKEN: ${xsrf}" -b "${cookie}" \
-d "grant_type=password&username=${user}&password=password&realm=${realm}" \
http://${cluster}:8889/api/foundry/security/oauth/token | python -mjson.tool \
| grep access_token | cut -d: -f2 | cut -d\" -f2`

Get CSRF token

You can use the method /csrf to obtain the XSRF token and Vert.x session token for use in subsequent MAPI calls.

HTTP request syntax (URI)

GET https://host_ip:9099/mapi/v1/csrf

Request structure

Not applicable.

Response structure

No applicable.

The XSRF token and Vert.x session token are returned in the response header as cookies with the names XSRF-TOKEN and vertx-web.session, respectively.

Return codes

Status code	HTTP name	Description
200	OK	The request was executed successfully.
405	Method Not Allowed	The specified HTTP method is not allowed. Resend using GET.

Example

Request example:

GET https://10.10.24.195:9099/mapi/v1/csrf

Viewing and using MAPI methods

Your system includes web-based documentation pages where you can view the MAPI methods for both the Object Storage Management and System Management applications, including the request bodies, request URLs, response bodies, and return codes for each. You can also use these pages to run each MAPI method.

You can use the MAPI documentation pages to experiment with the MAPI. Any requests you submit on the page take effect on the system.

NoteIf you specify UUIDs when creating resources, the UUIDs are ignored.

To use the MAPI page to run a method:

Procedure

In either the Object Storage Management App or the System Management App, select the user profile icon, in the upper right portion of the page.
Select:
- In the Object Storage Management App, select REST API.
- In the System Management App, select REST API - Admin.
A Swagger page opens for the selected MAPI.
Expand the category containing the method you want.
Select the row for the method you want.
To use an Object Storage Management method, enter the XSRF token in the field X-XSRF-TOKEN Header.
If the method you want needs a UUID:
1. Select the row for the GET method for the resource type that you want.
2. Click Try it out.
3. In the JSON response body, copy the value in the field uuid for the resource that you want.
If the method you want needs a request body:
1. In the section Parameters, under Model Schema, click inside the JSON text box.
  
  The JSON text is added to the field Value.
2. Edit the JSON in the field Value as needed.
  
  NoteSome methods might need other information in addition to or instead of UUIDs or JSON-formatted text. Some methods need particular string values or need you to browse for and select a file to upload.
Click Execute.
The method is executed and the results appear in the section Responses.

Including XSRF tokens in MAPI Swagger requests

Swagger does not automatically populate the X-XSRF-TOKEN header when executing Object Storage Management MAPI requests.

To obtain the token within a browser and include it in a MAPI request through Swagger:

Procedure

From the user profile icon on the top right of an Object Storage Management window, select REST API.
A Swagger page opens in a new tab.
Locate and copy the value of the cookie XSRF-TOKEN:
- In Chrome, from the Customize menu (in the upper right corner), select More tools > Developer tools. From the Developer Tools window select Storage > Cookies. Select and copy the value of the cookie XSRF-TOKEN.
- In Firefox, from the Open menu (in the upper right corner), select Web Developer > Storage Inspector. From the Developer Tools window select Cookies. Select and copy the value of the cookie XSRF-TOKEN.
Select the management API you want to execute and then click Try it out.
In the section X-XSRF-TOKEN, paste the value of the cookie into the field X-XSRF-TOKEN Header.

Results

You can now execute the method.

HTTP status response codes

When an HTTP request is sent to a server, the server sends back an HTTP response message. The HTTP response message consists of an HTTP header and, optionally, a message body. The response header contains an HTTP status code that gives the status of the request.

When an API request fails, the API returns:

An HTTP status code
Conditionally, a system-specific error code
A JSON-formatted error response body

The following table contains a list of HTTP status codes, their descriptions, and the types of HTTP requests that can generate each status code.

Status code	Meaning	Description	Methods
200	OK	The request was executed successfully.	PATCH POST
400	Bad Request	The request body contains one or more of these: An entry that is not valid A value for an entry that is not valid JSON formatting that is not valid If the request includes a UUID, the UUID might not be validly formatted.	PATCH POST
401	Unauthorized	Your access is not authorized. Possible reasons: No credentials are given with the request. The credentials provided with the request are not valid. A CSRF token is missing or not valid.	PATCH POST
403	Forbidden	You do not have permission to perform the request.	PATCH POST
404	Not Found	The resource you are trying to retrieve, edit, or delete cannot be found.	PATCH POST
405	Method Not Allowed	A request was made using a request method not supported by that resource; for example, using GET with a form that needs data to be presented using POST.	PATCH POST
409	Conflict	The resource you are trying to create already exists.	POST
500	Internal Server Error	The system experienced an error.
501	Unimplemented	An API was invoked that HCP for cloud scale doesn't support.	PATCH POST
503	Service Unavailable	The service is not available. Possible reasons: An external KMIP system has not been configured.	POST

System-specific error codes

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.

Status code	Description
4000	SSL certificate not trusted.

JSON response body

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

We've Moved!

Product Documentation has moved to docs.hitachivantara.com

Getting started with the management APIs

Input and output formats

Access and authentication

Requesting and submitting a CSRF token

Get CSRF token

Viewing and using MAPI methods

Including XSRF tokens in MAPI Swagger requests

HTTP status response codes

Still Looking?

Quick Links

Getting started with the management APIs

Input and output formats

Access and authentication

Requesting and submitting a CSRF token

Get CSRF token

Viewing and using MAPI methods

Including XSRF tokens in MAPI Swagger requests

HTTP status response codes