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 Amazon S3 APIs.

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 purposes of maintenance and repair. The HCP for cloud scale system provides functions to send notification of alerts, track and monitor throughput and performance, and trace actions through the system.

Getting started with Object Storage Management mangement APIs

HCP for cloud scale provides RESTful HTTPS interfaces 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 APIs (MAPIs) 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 MAPIs.

All URLs for the Object Storage Management MAPIs 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 MAPIs. Those MAPIs are separate and use a separate port. Those MAPIs are documented in the System Management application online help.

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 endpoint /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 required permissions for making API calls, see the System Management 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 endpoint /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 endpoint /auth/oauth in the System Management application API.
The payload of the request requires 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 provides 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, click the user profile icon, in the upper right portion of the page.
Select API.
Click on the row for the method you want.
If the method you want requires that you specify a UUID:
1. Click 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 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.
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 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 pane 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 pane select Storage > Cookies. Select and copy the value of the cookie XSRF-TOKEN.
Select the management API you want to execute and 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, 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 provides a status of the request.

The following table contains a list of returned status codes, descriptions, and the type of HTTP request that can generate the status code.

Status code	HTTP name	Description	Service
200	OK	The request was executed successfully.	PATCH POST
400	Bad Request	The request body contains one or more of these: An invalid entry An invalid value for an entry Invalidly formatted JSON If the request includes a UUID, the UUID may be invalidly formatted.	PATCH POST
401	Unauthorized	Your access is not authorized. Possible reasons: No credentials are provided with the request. The credentials provided with the request are invalid.	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 of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via 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 Object Storage Management mangement APIs

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 Object Storage Management mangement APIs

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