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 mangement API

HCP for cloud scale includes a RESTful HTTP interface for the following functions:

Managing storage components and Amazon Simple Storage Service (Amazon S3) settings
Managing administrative resources such as serial numbers and system events
Managing user resources such as S3 user credentials and OAuth tokens

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

You can execute all functions supported in the Object Storage Management application and the S3 User Credentials application using MAPI methods.

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

https://hcpcs_ip_address:9099/mapi/v1

NoteYou can execute all system configuration, management, and monitoring functions supported in the System Management application using System Management MAPI methods. Those methods are separate and use a separate port.

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.

Requesting and submitting an access token

You need to request an access token from the system. Send an HTTP POST request to the method /auth/oauth.

To use the API interface, the account you're using must have the appropriate permissions assigned, and you need a valid OAuth access token. For information about the permissions needed for making API calls, see the online help. The security access token, known as a Bearer token, authorizes all requests made to access and manage storage components and S3 settings in an HCP for cloud scale system.

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, send this command:
```
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.

To request an access token:

Procedure

Send an HTTP POST request to the method /auth/oauth in the System Management application API.
The payload of the request must include your username, password, and realm for a user account.The system sends you a JSON response body containing an access_token field. The value of this field is your token.
Include your access token as part of all REST API requests that you make by submitting an Authorization header along with your request.

Here's an example of requesting an authentication token 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 of this field is your token. For example:

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

Here's an example that uses cURL of including an access token as part of a request:

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

Viewing and using API methods

Your system includes web-based documentation pages where you can view all supported API methods, including the request bodies, request URLs, response bodies, and return codes for each. You can also use these pages to run each API method.

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

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

To use the API 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 API.
Select the row for the method you want.
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 for the uuid field for the resource that you want.
If the method you want needs 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.
NoteSome methods might need other information in addition to or instead of UUIDs or JSON-formatted text. Some need particular string values or need you to browse for and select a file to upload.
Click Try It Out!

Including security tokens in MAPI Swagger requests

HCP for cloud scale prevents cross-site request forgery by requiring an xsrf-token cookie and passing the header x-xsrf-token in API requests. Swagger does not automatically populate this header when executing MAPI requests.

To execute a MAPI request through Swagger:

Procedure

From the user profile icon on the top right of the Dashboard, select REST API.
Swagger opens in a new tab.
Locate 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.
- 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.
Select the management API you want to execute and then click Try it out.
Paste the value of the cookie into the field X-XSRF TOKEN.
Click Execute.

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 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.	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
501	Unimplemented	An API was invoked that HCP for cloud scale doesn't support.

We've Moved!

Product Documentation has moved to docs.hitachivantara.com

Getting started with the mangement API

Input and output formats

Requesting and submitting an access token

Viewing and using API methods

Including security tokens in MAPI Swagger requests

HTTP status codes

Still Looking?

Quick Links

Getting started with the mangement API

Input and output formats

Requesting and submitting an access token

Viewing and using API methods

Including security tokens in MAPI Swagger requests

HTTP status codes