Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

Introducing Hitachi Content Platform for cloud scale

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 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
  • Encryption of storage components
  • 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 this document. 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 an XSRF token

To protect against cross-site-request forgery, the Object Storage Management MAPI requires an XSRF token in all requests.

The Object Storage Management MAPI requires you to pass the XSRF token both in the request header and as a cookie within the request.

NoteThe 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 pass it as part of a request:

Procedure

  1. Obtain the token.

    The following command string obtains the token, locates it within the response, strips out extraneous text, and stores it as a variable:
    xsrf='curl -skc - https://hcpcs_cluster.com:9099/ \
    -H "user-agent: Mozilla" | grep XSRF-TOKEN | cut -d$'\t' -f 7'
  2. Include the token both in the request header and as a cookie within a MAPI request.

    The following command string uses an OAuth token defined as the variable $token in a MAPI request to list the user maria:
    curl -s -k -H "X-XSRF-TOKEN:${xsrf}" \
    -H "Authorization: Bearer $token" \
    -b "XSRF-TOKEN=${xsrf}" -H "accept: application/json" \
    -H "Content-Type: application/json" 
    -d '{"nameFilter": "maria"}' \
    -X POST https://hcpcs_cluster.com:9099/mapi/v1/user/list

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

  1. 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.

  2. 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.
  3. Expand the category containing the method you want.

  4. Select the row for the method you want.

  5. To use an Object Storage Management method, enter the XSRF token in the field X-XSRF-TOKEN Header.

  6. 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.

  7. 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.
  8. 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

  1. 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.
  2. 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.
  3. Select the management API you want to execute and then click Try it out.

  4. 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 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.

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 codeMeaningDescriptionMethods
200OKThe request was executed successfully.

PATCH

POST

400Bad RequestThe 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

401UnauthorizedYour access is not authorized. Possible reasons:
  • No credentials are given with the request.
  • The credentials provided with the request are not valid.

PATCH

POST

404Not FoundThe resource you are trying to retrieve, edit, or delete cannot be found.

PATCH

POST

405Method Not AllowedA 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

501UnimplementedAn API was invoked that HCP for cloud scale doesn't support.