Skip to main content

We've Moved!

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

Overview of the REST API

Use REST API specifications to manage, lock, and query resources, format requests and responses, and understand the system configuration, base URLs, object descriptions, and status codes.

System configuration of the REST API

This section explains the basic system configuration for using the REST API.

The following shows the basic system configuration of the REST API.

GUID-494D1FC8-329B-43DE-AE62-FA939734DAF0-low.gif
  • Storage system

    By using the REST API, you can get information from the storage system or change the configuration of the storage system. The REST API can perform operations on the following storage systems:

    • VSP F350, F370, F700, F900
    • VSP G350, G370, G700, G900
  • GUM (Gateway for Unified Management)

    This is the computer that has basic management functions for the storage system. You can manage storage system from an external device through communications with GUM.

    GUM exists in each controller, CTL1 and CTL2.

  • REST API server

    This is a component that acts as a server to receive REST API requests from REST API clients, issue orders to the storage system, and then return the execution results to the REST API clients.

    The REST API server is included in the GUM of the storage system.

    Note

    The REST API servers that are allocated on the GUM of CTL1 and CTL2 operate independently. Therefore, when a failure occurs in one GUM, the REST API server on the other GUM can be used to run the operation. However, the following information is not inherited by the REST API servers:

    • Job information
    • Remote storage system information

    If necessary, register information about the remote storage systems to the other REST API server.

  • REST API clients

    The REST API clients issue requests to the REST API server. The term "REST API client" refers to software or scripts that use the REST API.

With the REST API, you can run API requests other than those described in this manual, such as API requests that get information in a simple format and API requests that return responses at a high speed. For details about these API requests, see Hitachi Vantara Knowledge.

NoteThe REST API server internally links with the CCI of the GUM. The maximum number of CCI instances used by the REST API server is 1000, in the range from 1048 to 2047. If you use the CCI of the GUM for a purpose other than the REST API, use an instance number that is not in the range from 1048 to 2047.

Requirements for SSL communications

This section describes how to set up SSL communication for the REST API.

With the REST API, you can use SSL communication between the REST API clients and the REST API server.

For SSL communications between REST API clients and the REST API server, the server certificate for HTTPS installed in the GUM is used. By default, this server certificate is a self-signed certificate. For this reason, a communication error might occur depending on the client program. To resolve this issue, do one of the following:

  • Change the certificate of the storage system to a server certificate trusted by a certificate authority, such as VeriSign.

    For details on how to obtain a certificate signed by a certificate authority and how to update the certificate on the GUM, see the System Administrator Guide.

  • Correct the client programs to avoid errors.

    The approach taken to correct client programs to avoid errors varies by programming language.

    For example, if the Requests library is used with Python, verification of the server certificate can be omitted if verify=False is specified when a request is issued.

Note

TLS version 1.2 can be used for SSL communication between REST API clients and the REST API server.

The following encryption methods (cipher suites) can be used:

  • ECDHE-RSA-AES256-GCM-SHA384
  • ECDHE-RSA-AES128-GCM-SHA256
  • AES256-GCM-SHA384
  • AES256-SHA256
  • AES128-GCM-SHA256
  • AES128-SHA256

Specifying the resource to be managed

In REST API, domains are separated for each type of operation. The URL format differs for each domain. The domains used in REST API and the URL format are as follows:

  • Objects domain:

    A domain for defining operations on each object subject to REST API operations, such as operations on storage system resources (for example, LDEVs or pools). Specify the URL in the following format:

    protocol://host-name:port-number/ConfigurationManager/version/objects
  • Services domain:

    A domain for defining the services provided by the REST API server. Services indicate batch operations for multiple objects, or operations for using or changing the configuration of the REST API server, such as locking or unlocking a resource group. Specify the URL in the following format:

    protocol://host-name:port-number/ConfigurationManager/version/services
  • Configuration domain:

    A domain for defining settings related to the REST API server, for example, collecting REST API version information. Specify the URL in the following format:

    protocol://host-name:port-number/ConfigurationManager/configuration
  • Base URL:

    protocol://host-name:port-number/ConfigurationManager
    • Protocol: Specify https or http. We recommend specifying https for security.

    • Host name: Specify the IP address of the GUM or a host name that can be resolved.

    • Port number: Specify the port number to be used for communications with the REST API server. The default port number is 443 for SSL communications, and 80 for non-SSL communications. The port number can be omitted if the default port number is used for communications.

    • Version: Specify the version of the REST API. Currently, only v1 can be specified.

Tip

You can also specify the URL in the same format used for the Configuration Manager REST API. Specify the URL in the following format:

  • For the objects domain
    protocol://host-name:port-number/ConfigurationManager/version/objects/storages/storage-device-ID
  • For the services domain
    protocol://host-name:port-number/ConfigurationManager/version/storage-device-ID/services

For the storage device ID, specify a 12-digit value consisting of the fixed value designated for the model of the storage system and the storage system's 6-digit serial number. The fixed value designated for the storage system model is as follows.

Storage system

Fixed value

VSP F370, F700, F900

VSP G370, G700, G900

886000

VSP F350

VSP G350

882000

VSP G130#

880000

#: This model is available only in select markets. Contact your local sales representative for availability.

  • The following describes the URL formats supported by each domain.

    For the objects domain:

    URL formats (excluding the base URL)

    HTTP method

    Operations

    /v1/objects/storages

    GET

    Obtain general information about the target storage system

    /v1/objects/storages/instance

    You can also specify the URL in the following format:

    /v1/objects/storages/storage-device-ID

    GET

    Obtain detailed information about the target storage system

    /v1/objects/object-type

    You can also specify the URL in the following format:

    /v1/objects/storages/storage-device-ID/object-type

    GET

    Obtain a list of multiple objects

    POST

    Create new objects

    /v1/objects/object-type/object-ID

    You can also specify the URL in the following format:

    /v1/objects/storages/storage-device-ID/object-type/object-ID

    GET

    Obtain an object

    PATCH

    Change an attribute of an object

    DELETE

    Delete an object

    /v1/objects/object-type/object-ID/actions/action-name

    You can also specify the URL in the following format:

    /v1/objects/storages/storage-device-ID/object-type/object-ID/actions/action-name

    GET

    Obtain the action template for an object

    /v1/objects/object-type/object-ID/actions/action-name/invoke

    You can also specify the URL in the following format:

    /v1/objects/storages/storage-device-ID/object-type/object-ID/actions/action-name/invoke

    POST

    Run an action on an object

    For the services domain:

    URL formats (excluding the base URL)

    HTTP method

    Operations

    /v1/services/service-name/actions/action-name/invoke

    You can also specify the URL in the following format:

    /v1/storage-device-ID/services/service-name/actions/action-name/invoke

    POST

    Run a specific action of the service

    For the configuration domain:

    URL formats (excluding the base URL)

    HTTP method

    Operations

    configuration/version

    GET

    Obtain the version information of the REST API

The following is an example of a URL:

https://192.0.2.100/ConfigurationManager/v1/objects/ldevs

Specifying an object ID

An object ID is an ID that is used to uniquely identify a resource. An object ID is used when specifying a specific resource in a URL.

You can use the following two methods to specify an object ID:

  • (Recommended) Run the GET operation to obtain the object ID from the execution result.

    Example: When specifying the object ID of an LDEV

    If the object type is ldevs, because the object ID of the LDEV is unique in the storage system, use the object ID obtained by running the GET operation without changing the ID. If the object ID of the LDEV is 100, specify as follows:

    ldevs/100
  • Generate an object ID by using the character string that connects multiple attribute values with commas.

    Example: When specifying the object ID of a host group

    If the object type is host-groups, the object ID of the host group can be generated by connecting, with a comma, the attribute value of the port and the attribute value of the host group that belongs to the port. If the attribute value representing the port is CL1-A, and the attribute value representing the host group which belongs to the port is 200, specify as follows:

    host-groups/CL1-A,200

To generate an object ID by connecting multiple attribute values with commas, the attribute value must be encoded in accordance with the RFC3986 on the REST API client. After all attribute values are encoded, specify the character string that connects multiple attribute values with commas to be the object ID. Typical symbols which need encoding are shown below.

Pre-Encode

Post-Encode

! (exclamation mark)

%21

# (number sign)

%23

$ (dollar sign)

%24

% (percent)

%25

& (ampersand)

%26

' (single quotation mark)

%27

( (left parenthesis)

%28

) (right parenthesis)

%29

* (asterisk)

%2A

+ (plus sign)

%2B

, (comma)

%2C

: (colon)

%3A

; (semicolon)

%3B

= (equal sign)

%3D

? (question mark)

%3F

@ (at sign)

%40

[ (left square bracket)

%5B

] (right square bracket)

%5D

Here is an example of specifying the object ID of the CHAP user from the following attribute values:

"portId": "CL1-A"

"hostGroupNumber": 234

"wayOfChapUser":"TAR"

"chapUserName": "pmd2g,user1"

After the comma contained in the value of chapUserName is encoded to %2C, the object ID of the CHAP user is the following character string, which connects the values with commas:

CL1-A,234,TAR,pmd2g%2Cuser1
Note
  • If the object ID is obtained by performing the GET operation, the REST API server returns an encoded value. To use the object ID obtained by performing the GET operation in a request of another operation, use the object ID without decoding it.
  • If you want to create a new object or change an attribute, we recommend that you do not specify values that contain the reserved characters listed above.

Supported HTTP methods

HTTP defines methods, which are operations that can be performed on resources.

The REST API supports the following HTTP methods.

HTTP method

Description

Processing method

GET

This method gets object information. Alternatively, this method gets a list of objects.

For example, this method can obtain a list of pools.

Synchronous

POST

  • This method creates new objects.

    For example, this method can create pools.

  • This method can perform specific actions to objects.

    For example, this method can expand pools.

Asynchronous

However, the following APIs are performed in synchronous processing.

  • Generating sessions
  • Uploading the files required for initial configuration
  • Getting information about an iSCSI target of a port on an external storage system
  • Performing a login test on an iSCSI target of an external storage system that is registered to a port on the local storage system
  • Backing up encryption keys

PATCH

This method changes the attributes or the state of an object.

For example, this method can change the pool threshold.

Asynchronous

However, the following API is performed in synchronous processing.

  • Setting the system date and time of a storage system

DELETE

This method deletes objects.

For example, this method can delete pools.

Asynchronous

However, the following APIs are performed in synchronous processing.

  • Discarding sessions

The following explains the processing method for the REST API (synchronous processing and asynchronous processing):

  • For synchronous processing, the processing results are returned in the response.
  • For asynchronous processing, the operation on the resource is registered as a job. In addition, the job information and the HTTP status code 202, which indicates that the processing has been accepted, are returned in the response. Subsequently, the registered job runs asynchronously. If registration of a job fails, the HTTP status code 500 is returned.
    Tip
    • If you specify Completed for the Response-Job-Status in the request header (even for asynchronous processing operations), a response will be returned only after the job is complete.
    • For pair operations, you can use Job-Mode-Wait-Configuration-Change in the request header to specify the time when the job status changes to Completed. If you specify NoWait in the request header, the job status will change to Completed without waiting for data copying to finish.

User authentication

User authentication is required to operate the storage system. To perform user authentication, the Authorization header must be specified.

In the REST API, session-based user authentication is performed. A session is always generated first when a REST API client accesses the REST API server and starts an operation. In the request that generates a session, the user ID and password are used for authentication to access the storage system. After a session is created, specify session information for the Authorization header to perform authentication based on the session information.

Authentication by the user ID and password

When you create a session, specify authentication information in the following format in the Authorization header:

Authorization: Basic authentication-information
  • authentication-information

    Specify a base64-encoded character string in which the user ID and password are concatenated with a colon (:). Use the user ID and password of a user account that can perform operations on storage system resources.

When using the REST API, you can use the following characters for the user ID and password.

Item

Number of characters

Specifiable characters

User ID

1 to 63 characters

You can use the following characters.
  • Alphanumeric characters
  • The following symbols:

    ! # $ % & ' * + - . / = ? @ ^ _ ` { | } ~

Password

6 to 63 characters

You can use the following characters.
  • Alphanumeric characters
  • ASCII symbols which can be keyed in except space:

    ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

The following is an example of the Authorization header where the user ID is sample-user, and the password is sample-password:

Authorization: Basic c2FtcGxlLXVzZXI6c2FtcGxlLXBhc3N3b3Jk
Authentication by sessions

Specify the token for the session in the following format in the Authorization header:

Authorization: Session token
  • Token

    A token is authentication information that is returned after a session is created. This information is used to determine whether the request was issued from an authorized user.

Example of the Authorization header:

Authorization: Session 550e8400-e29b-41d4-a716-446655440000

Session management

In the REST API, a session is used to identify multiple requests as a series of operations to be performed by the same client. For example, if a user wants to use the same account to run two client programs in parallel, the user must generate a session for each client program. On the REST API server, each program is identified based on session information. In addition, when the REST API is used to exclusively lock the resources to be operated, the REST API controls the locks on a session basis.

A session is always generated when a REST API client accesses the REST API server and starts an operation on a storage system. After a session is generated, a session ID and token are returned to the client. In subsequent operations, specify the token for the Authorization header of each request, as authentication information. To terminate operations from a REST API client, discard sessions to prevent sessions that are no longer required from remaining on the server.

Generating a session

A REST API session is created when the user runs the API that generates a session. A user can generate multiple sessions. The maximum number of sessions that can be used is 64 per DKC.

After the session is generated, the following information is returned to the client as a response:

  • Session ID

    ID used for identifying a session on the REST API server. A session ID is used to check whether the session is valid or to discard the session. The user who created the session, or a user who belongs to the Administrator user group (built-in user group) can view the session ID.

  • Token

    Information that is used to identify the source that issues requests as a specific user. A token is used to decide whether the request is issued during the same session. Only the user who created the session can view the token.

Running an API request by using a session

To use a session to run an API request, specify a token for the Authorization header of the request as authorization credentials. The requests for which the same token is specified are handled as the operation during the same session. The following is an example of specifying the Authorization header with a token specified.

Authorization : Session d7b673af189048468c5af9bcf3bbbb6f

If a session goes unused for a certain period of time, it is automatically discarded (session timeout). The time that elapses until a session timeout is the time that has elapsed since the session was generated or the execution result of the request for which the session was specified was returned. The wait time during synchronous processing and the wait time for the response of an asynchronous processing API request are not included in that time. If a request that uses that session is issued during the time that elapses until a session timeout, the time is reset. The time until a session timeout is 300 seconds (5 minutes) by default. However, you can specify the time until a session timeout when a session is generated.

To prevent the session for an operation that is in progress from being discarded by a timeout, periodically issue a request that uses the session.

Tip

If the information (such as the role and resource group) about the user who generated the session is changed while the session is being used, the changes are applied to the operation even while the session is being used. If the password of the user who generated the session is changed, the session might be discarded.

Discarding a session

If you no longer need to manage sessions after finishing a series of operations, discard the sessions. Sessions can be discarded only by the user who generated the sessions, or a user who belongs to the Administrator user group (built-in user group) .

If you have locked the resources by specifying a session, the resources will be unlocked when the session is discarded.

Request headers

This section describes the request headers supported by the REST API.

Header

Category

Description

Specifiable value

Accept

Optional

Specifies the media type of the response.

*/* (json)

Default value: */* (json)

Content-Type

Optional

Specifies the media type of the request body.

If a request body is specified, the Content-Type header is specifiable. If a request body is not specified, this header is ignored even if specified.

application/json

Default value: application/json

Content-Length

Optional

Specifies the size of the request body.

You can specify the Content-Length header when specifying a request body. This header is automatically assigned depending on the specifications of the client software.

Specify the header, in bytes.

Default value: None

Authorization

Required

Specifies the authorization method and authorization credentials.

You do not need to specify this header for the API function that gets version information or for the API function that gets a list of storage systems.

Specify the header in one of the following formats:

  • Basic authorization-credentials

    For the authorization credentials, specify the user ID and password in a character string encoded by using Base64. Use the user ID and password of a user account that can perform operations on storage system resources.

  • For cases other than the above:

    Session token

    When the session was generated:

    Specify a token that was obtained when the session was generated.

Default value: None

Remote-Authorization

Required (for the API for the object types on the right)

Specifies the authorization credentials to be used when accessing the remote storage system. This header is used in the API for the following object types:

  • remote-mirror-copygroups
  • remote-mirror-copypairs
  • remote-storages

Specify the header in the following format:

Session token

Specify the token for the session that was generated in the remote storage system.#

Default value: None

Response-Max-Wait

Optional

Specifies the maximum wait time until a response is returned when an API request for asynchronous processing is issued. A response is returned when the specified time elapses after the REST API server accepted the API request.

If the processing finishes before the maximum wait time elapses, a response is returned at the time of completion.

Factors such as network status and load of the REST API server can delay acceptance of a response, so the wait time might be longer than the specified maximum time. Take these factors into account when specifying the maximum wait time.

Integers between 0 and 1800

Unit: Seconds

Default value: None

Response-Job-Status

Optional

Specifies the status of the job that is expected to return a response when an API request for asynchronous processing is issued. A response is returned when the job transits to the specified status or when the processing stops due to an error.

Specify the header in one of the following formats:

job-status;

or

job-status; Job-State=state-of-the-job

Default value: None

Job-Mode-Wait-Configuration​-Change

Optional

Specifies when the job status is to be changed to Completed when an API request for asynchronous processing is issued in pair operations.

Use this header for the API functions that meet the following conditions.

  • The object type is one of the following:
    • local-clone-copygroups
    • local-clone-copypairs
    • remote-mirror-copygroups
    • remote-mirror-copypairs
  • The HTTP method is either of the following:
    • POST
    • PATCH

Specify either of the following values:

  • Wait: Wait for data copying to finish, and then change the job status to Completed.
  • NoWait: Change the job status to Completed without waiting for data copying to finish.

If you specify NoWait, data copying continues even after the job status changes to Completed. To check whether data copying has finished, check the status of the target resource.

Default value: Wait

#: Specify at least 60 seconds for the timeout time of a session generated on the remote storage system. If you specify less than 60 seconds, the session on the remote storage system might time out, causing the execution of a request to fail.

If a header other than the above is specified, the specified header is ignored.

Response-Max-Wait and Response-Job-Status can be specified in combination. If both are specified, a response is returned when either condition is satisfied.

If neither Response-Max-Wait nor Response-Job-Status is specified, a response is returned immediately.

Response headers

This section describes the response headers returned by the REST API server.

Header

Description

Default

Content-Type

Indicates the media type of the response data.

application/json;charset=UTF-8

WWW-Authenticate

Indicates that authentication is required when the HTTP status code 401 is returned.

  • When a session is created:

    Basic realm="Block storage"

  • For other cases:

    Session realm="Block storage"

HTTP status codes

The REST API uses the following standard HTTP status codes to indicate the processing results.

Status codes

Description

200

Success

The request has been processed properly. Even if the number of results obtained is 0 in a request to get information, this status code will be returned.

202

Accepted

The request for asynchronous processing has been accepted.

400

Bad request

The request header, the query parameter, or the request body is invalid.

401

Unauthorized

The Authorization header is not specified in the request header. Alternatively, authentication using the information specified in the Authorization header has failed.

403

Forbidden

You do not have the permission required to perform the operation.

404

Not found

The resource specified by the URL is not found. Alternatively, you do not have read permission for the resource.

405

Method not allowed

The specified method is not allowed for the resource specified by the URL.

406

Not acceptable

The media type specified in the Accept header is not supported.

409

Conflict

A request is made to change the status of the resource specified by the URL, in a way that the change might cause conflicts or be impossible.

Example: A request is made to create one resource that has the same ID as another resource that has already been created.

411

Length Required

The Content-Length header must be specified.

412

Precondition failed

The conditions for running the API request are not met.

415

Unsupported media type

The media type specified in the Content-Type header is not supported.

417

Expectation Failed

The specified Expect header is invalid, or the Expect header is not supported by the web server.

500

Server error

An internal error has occurred in the REST API server or the storage system that is the operation target.

502

Proxy Error

There is no response from the REST API server.

503

Service unavailable

The request cannot be accepted, because the REST API server or the storage system is busy.

If this status code is returned, run the request again.

API-specific information about status codes is explained in the sections on the specific APIs.

Note

When REST API is used for a long period, the following response may be returned.

  1. An HTML form response body is returned with the status code 500 for a several minutes.
  2. When executing the API except discarding the sessions API, a blank response body is returned with the status code 200.

    After that, the symptom described in 1. occurs.

In this case, execute the API again until an HTML format response is not returned with the status code 500.

Request and response formats

Use the JSON format to specify attribute values when creating or changing a resource. Also, use the JSON format for the results of resource information acquisition.

When creating or adding a resource by using the POST method, or when changing or editing a resource by using the PATCH method, specify resource attributes in JSON format. When you use the GET method to collect resource information, responses are returned in JSON format.

The supported character encoding is UTF-8.

Request format
  • If you specified a null character for a string-type attribute, the value of the attribute is assumed to be null.

  • If you specified a null character for an attribute whose type is not string, the attribute is assumed to be unspecified.

  • You can use the following characters in attribute values:

    Uppercase letters (A-Z), lowercase letters (a-z), numbers (0-9), commas (,), hyphens (-), periods (.), colons (:), at marks (@), and underscores (_)

    Allowable characters vary for each API request. For details, refer to individual API command pages.

    Note
    • If you specified a character string containing a comma, a colon, or an at mark, you must encode the symbol when generating the object ID. We recommend that you do not use these symbols. If you generate the object ID without encoding these symbols, the URL when an API request is issued might be incorrect and cause an error.
    • You cannot specify a hyphen as the first character of the value.
  • Do not include backslashes (\) or forward slashes (/) in URLs.

  • If you specify an IP address, you cannot use an IPv4-mapped address.
Response format
  • If the API processing succeeds, a response is returned in JSON format.
  • If the processing fails, depending on the contents of the error, a response in HTML format, instead of JSON format, might be returned.

    To resolve the error based on the HTTP status code in the program, check the value of Content-Type in the response header.

Tip

The following example is used to describe how to read the error message that appears if the string specified in the request body contains a syntax error.

Request body:

{
  "parameters": {
    "status": blk
  }
}

Error message:

{
  "errorSource": "/ConfigurationManager/v1/objects/ldevs/5/actions/change-status/invoke",
  message": "The format of the string or the content specified in the request body is invalid. (details = Unexpected character ('b' (code 98)): expected a valid value (number, String, array, object, 'true', 'false' or 'null')\n at [Source: java.io.ByteArrayInputStream@10f607b; line: 3, column: 16])",
"  "solution": "Check and, if necessary, revise the specified request body so that the format and content are correct.",
  "messageId": "KART40046-E"
}

The location where the error occurred is output after at in the message details. This example indicates the error is in line: 3, column: 16.

In column 16 of line 3 in the request body, you can see that the status attribute, which should be specified as a string, is specified incorrectly.

Query parameters

If the GET method is used to obtain an object, query parameters can be specified to filter the execution results based on specific conditions.

Query parameters can be specified at the end of the URL in the following format:

?parameter=value

To specify multiple parameters, concatenate them by using ampersands (&). Multiple parameters are specified in the following example:

?parameter=value&parameter=value...

For details on parameters that can be specified for queries, see the section describing the specific API request.

Parameters are case sensitive. If you specify a parameter other than those that can be specified for each API, the invalid parameter is ignored, and only the valid parameters are used to filter the execution results.

If a parameter value contains a reserved character defined in RFC 3986, specify an encoded character string. For details about the reserved characters defined in RFC 3986, see the section describing how to specify an object ID.

If you specify an IP address for a parameter value, you cannot use an IPv4-mapped address.

Note

When you obtain an object by specifying query parameters, if the storage management software or another REST API client is performing a configuration-change operation on the object, you might not be able to obtain the correct information. To obtain the correct information, be sure to obtain a lock before obtaining the object.

Data type

This section describes the data types that can be specified by using the REST API.

The following table shows the data types supported by the REST API and the corresponding JSON data types.

Data type

JSON type

Description

boolean

boolean

A type that represents true or false.

Example :true

int

number

A type that represents a 32-bit signed integer.

Example :100

long

number

A type that represents a 64-bit signed integer.

Example :1048576

string

string

A type that represents a character string.

Example :"host_group_1"

ISO8601string

string

A type that represents time in the ISO 8601 extended format (YYYY-MM-DDThh:mm:ssZ).

The only time zone that you can specify is UTC.

Example :"2015-03-20T09:27:35Z"

link

string

A type that represents the path of a URL.

The link type indicates a URL for a resource. For example, when a request for asynchronous processing is issued, a URL for the job object is returned by using the link type.

The link type data is a character string of the URL from which the protocol, host name, and port number are excluded. If the URL is created based on the link type data, you must add the protocol, host name, and port number.

Example :

"/ConfigurationManager/v1/objects/ldevs/100"

In addition to the preceding data types, the following JSON data types are also used:

  • The object type

    The character string, in which the attribute and value are connected with a colon (:), is enclosed in { and }. If more than one attribute-value pair exists, the pairs are separated by commas.

  • The array type

    The character string, in which multiple values are separated by commas, is enclosed in [ and ].

Output format

After an API request is issued, a response is returned based on the API processing method, the API processing type, and the execution result.

The following table shows the response output formats when the processing of the request is successful.

API processing method

API processing type

Status code of the execution result

Output format

Synchronous processing

GET (getting a single object)

200

See the description in the response message for each API function.

GET (getting multiple objects)

200

Data object

GET (getting an action template)

200

Action template object

Other than the preceding

200

See the description in the response message for each API function.

Asynchronous processing

All

202

Job object

If the processing of the request fails, an error object is returned as a response.

Data object

Data object is an object for returning the object list.

The following table shows the data object schema.

Attribute

Data type

Description

data

array

Object list

The following shows an example of a data object:

{
  "data": [
      {
          "parityGroupId":"5-2",
          "numOfLdevs":3,
          "usedCapacityRate":45,
          "availableVolumeCapacity":4000,
          "raidLevel":"RAID5",
          "raidType":"2D+2D",
          "clprId":0,
          "driveType":"DKR5C-J600SS"
      },
      {
          "parityGroupType",
          ...
      },
       ...
  ]
}

Job object

A job object represents job information that is returned when an API request for asynchronous processing is issued.

The following table explains the schema of a job object.

Attribute

Data type

Description

jobId

long

Job object ID.

self

link

URL used to access the job information.

userId

string

ID of the user who issued the API request that triggered registration of the job.

status

string

Status of the job.

The following values can be returned:

  • Initializing: The job is being initialized.

  • Running: The job is running.

  • Completed: Execution of the job is finished.

state

string

State of the job.

The following values can be returned:

  • Queued: The job has been queued.

  • Started: The job has been started.

  • StorageAccepted: The request was received by the storage system#.

  • Succeeded: The job finished successfully.

  • Failed: The job failed.

  • Unknown: The state of the job is unknown.

createdTime

ISO8601string

Time when the job was created.

updatedTime

ISO8601string

Time when the state of the job was updated.

completedTime

ISO8601string

Time when the job ended.

request

Request Object

Object that retains information about the request.

affectedResources

link[]

URL used to access the resource targeted by the operation.

If one API request performs operations on multiple resources, the URLs of all those resources are returned. If a job failed, only the URLs of the resources for which processing is confirmed to have been completed are returned.

If the resource is deleted successfully, the URL of the deleted resource is returned. A 404 error occurs if this URL is accessed. This confirms that the resource has been deleted successfully.

The attribute affectedResources is also included in the API response that obtains job information. In this case, the URL used to access the resource targeted by the API command that triggered registration of the job is returned.

error

Error Object

Object that retains error information.

#: The state StorageAccepted is returned only for a job that creates a remote copy pair.

Note

A maximum of 3,000 instances of job information can be retained. If the number of instances of job information exceeds 3,000, the instances of the oldest "createdTime" are deleted first.

Example of a job object when the job execution starts:

{
  "jobId": 111111,
  "self": "/ConfigurationManager/v1/objects/jobs/111111",
  "userId": "user1",
  "status": "Running",
  "state": "Started",
  "createdTime": "2015-04-01T08:00:00Z",
  "updatedTime": "2015-04-01T08:05:00Z",
  "request": {
    "requestUrl": "/ConfigurationManager/v1/objects/ldevs",
    "requestMethod": "POST",
    "requestBody": "{\"ldevId\" : 112, \"poolId\" : 100, \"blockCapacity\" : 1000}"
  }
}

Example of a job object when the job is finished successfully:

{
  "jobId": 222222,
  "self": "/ConfigurationManager/v1/objects/jobs/222222",
  "userId": "user1",
  "status": "Completed",
  "state": "Succeeded",
  "createdTime": "2015-04-01T08:00:00Z",
  "updatedTime": "2015-04-01T08:10:00Z",
  "completedTime": "2015-04-01T08:10:00Z",
  "request": {
    "requestUrl": "/ConfigurationManager/v1/objects/ldevs",
    "requestMethod": "POST",
    "requestBody": "{\"ldevId\" : 112, \"poolId\" : 100, \"blockCapacity\" : 1000}"
  },
  "affectedResources": [
    "/ConfigurationManager/v1/objects/ldevs/112"
  ]
}

Example of a job object when the job failed:

{
  "jobId": 333333,
  "self": "/ConfigurationManager/v1/objects/jobs/333333",
  "userId": "user1",
  "status": "Completed",
  "state": "Failed",
  "createdTime": "2015-04-01T07:00:00Z",
  "updatedTime": "2015-04-01T07:01:00Z",
  "completedTime": "2015-04-01T07:01:00Z",
  "request": {
    "requestUrl": "/ConfigurationManager/v1/objects/ldevs",
    "requestMethod": "POST",
    "requestBody": "{\"ldevId\" : 112, \"poolId\" : 100, \"blockCapacity\" : 1000}"
  },
  "error": {
    "errorSource": "/ConfigurationManager/v1/objects/ldevs",
    "messageId": "KART30000-E",
    "message": "An error occurred in the storage system. (message = The state of the pool is incorrect.)",
    "cause": "An error occurred during execution of a CCI command.",
    "solution": "See the manual of the CCI and remove the cause of the error.",
    "solutionType": "SEE_ERROR_DETAIL",
    "errorCode": {
      "SSB1": "2E10",
      "SSB2": "6014"
    },
    "detailCode": "30000E-2-2E10-6014"
  }
}

Error object

An error object represents error information that is returned when the request processing fails.

If the API processing fails, an error object is returned as response data. The following explains the schema of an error object.

Attribute

Data type

Description

errorSource

link

URL where the error occurs

messageId#

string

Message ID

message

string

Content of the error message

cause

string

Cause of the error

solution

string

Solution to the error

solutionType

string

Category of the solution to the error

  • RETRY: Error that can be resolved by retrying the request
  • SEE_ERROR_DETAIL: Error that must be resolved by taking the action described in the error message

If RETRY is returned as the value of this attribute, retry the request that failed.

You can check the details of the request by checking the value of request of the job object.

errorCode

object

Error code from the storage system

A value is returned only if an error occurs in the storage system and thus one of the following error codes is issued.

  • The SSB1 code and SSB2 code of CCI
  • An error code of CCI

Storage system error codes are required for maintenance of the storage system.

detailCode

string

Detailed information about the error

The information is displayed in the following format:

nnnnnZ-TYPEoutput-format-for-each-TYPE

Example:

40097E-1-30000E-2-2EDA-00EE
  • nnnnnZ

    Displays the message ID of the REST API.

    • nnnnn

      Serial number of the message

    • Z

      Message type

      I : Information

      W : Warning

      E : Error

  • TYPE

    Displays the type of the error.

    • 0: An error that occurred on the REST API server side

    • 1: An error that occurred on the REST API server on the remote storage system side (for remote copy)

    • 2 to 4: An error that occurred on the storage system side

  • output-format-for-each-TYPE

    The output format varies depending on the value of TYPE.

    • When the value is 0:

      No information is output.

    • When the value is 1:

      The value of the detailCode attribute for the REST API server on the remote storage system side is displayed.

    • When the value is 2:

      Information about the CCI error is displayed in the following format:

      - SSB1-code- SSB2-code

      For details, see the CCI manual.

    • When the value is 3:

      An error code of CCI is displayed.

      For details, see the CCI manual.

    • When the value is 4:

      Information about an error that occurs in the GUM is displayed in the following format:

      - part-code- error-code

      For details, see the manual Hitachi Device Manager - Storage Navigator Messages.

#: The name of the attribute is sometimes returned as the messageID.

Example of an error object that might be returned if an error occurs in the REST API server:

{
  "errorSource": "/ConfigurationManager/v1/objects/ldevs",
  "messageId": "KART20008-E",
  "message": "Required parameters are not specified.",
  "solution": "Check parameters.",
  "solutionType": "SEE_ERROR_DETAIL",
  "detailCode": "20008E-0"
}

Example of an error object that might be returned if an error occurs in the storage system:

{
  "errorSource": "/ConfigurationManager/v1/objects/ldevs/16",
  "messageId": "KART30000-E",
  "message": "An error occurred in the storage system. (message = The state of the pool is incorrect.)",
  "cause": "An error occurred during execution of a CCI command.",
  "solution": "See the manual of the CCI and remove the cause of the error.",
  "solutionType": "SEE_ERROR_DETAIL",
  "errorCode": {
    "SSB1": "2E10",
    "SSB2": "6014"
  },
  "detailCode": "30000E-2-2E10-6014"
}

The following shows an output example of the detailCode attribute:

If an error occurs on the REST API server (message ID: KART40231-E)

"detailCode": "40231E-0"

If an error occurs on the REST API server on the remote storage system side (message ID: KART40097-E, value of the detailCode attribute for the REST API server on the remote storage system side: 30000E-2-2EDA-00EE)

"detailCode": "40097E-1-30000E-2-2EDA-00EE"

If an error occurs on the storage system side (message ID: KART30000-E, SSB1 code: 2EDA, SSB2 code: 00EE)

"detailCode": "30000E-2-2EDA-00EE"

If an error occurs on the storage system side (message ID: KART30000-E, CCI error code: EX_INVARG)

"detailCode": "30000E-3-EX_INVARG"

If an error occurs on the storage system side (message ID: KART30007-E, part code: 30762, error code: 204092)

"detailCode": "30007E-4-30762-204092"

Request object

Request objects are objects for retaining request information.

The following explains the schema of a request object.

Attribute

Data type

Description

requestUrl

link

URL requested by the API for asynchronous processing.

If the character string of the URL exceeds 2,048 bytes, the character string will be truncated.

requestMethod

string

HTTP method requested by the API for asynchronous processing.

requestBody

string

Request body requested by the API for asynchronous processing.

If the character string of the request body exceeds 1,024 bytes, the character string will be truncated.

Action template object

An action template object is a template of request bodies that are required to run actions. Get action template objects by using the GET method. Specify values in the template according to the action that you want to run. Specify the request body, and then run the action.

The following table shows the schema of the action template object.

Attribute

Data type

Description

parameters

object

Parameters required for the operation

The following shows the action template for expanding the volume capacity, as an example of an action template object:

{
  "parameters": {
    "additionalBlockCapacity": null
  }
}

In an action template, the attributes that must be specified to run an action are written beforehand. For the values, null or [] is set to indicate that the values are unspecified. Specify a value for these attributes. In the preceding example, the two attributes used to specify the amount of the capacity to be added to a volume are written.

In the following example, values are specified in the collected action template:

{
  "parameters": {
    "additionalBlockCapacity": 500
  }
}

In the request body, specify an action template in which unnecessary attribute lines have been deleted and attribute values have been set for the remaining necessary attribute lines, and then run the action.

Locking resources

If multiple REST API clients simultaneously attempt to perform operations on the same resource, unexpected configuration changes might be performed, with results other than those anticipated. In the REST API, the user can lock the resource group allocated to them so that other users cannot change the configurations of resources in the locked resource group.

The REST API controls locks on a session basis. All resources of the resource group allocated to the user who generated a session are locked. When the resource group allocated to you is locked by another user, you cannot obtain a lock for the resource group.

Only the session used for the request that locked a resource can run a configuration-change request for the locked resource. If one user account generated multiple sessions, a configuration-change request cannot be run if the specified session is different from the session used to lock the resource. (If the specified session is different, even if it is generated by the same user account, the session cannot run the configuration-change request.)

However, operations that do not change the configurations of the resources on the storage system, such as a change of a pair status and operations for the REST API server, can be run without being affected by exclusive control by locking. The following operations are not affected by locking:

  • Generating or discarding a session
  • Registering or deleting remote storage system information on the REST API server
  • Changing the status of a copy pair or snapshot (split, resynchronize, and restore)
  • Getting information

    Note that, when you obtain information by specifying query parameters, you might not be able to obtain the correct information because the operation might be affected by configuration-change operations performed by other REST API clients or by the storage management software. To obtain the correct information, be sure to lock the relevant resources before performing the operation.

  • Setting the system date and time of a storage system
  • Uploading the files required for initial configuration

When a single user account uses multiple sessions, only one of the sessions can be used to lock resources.

When operations are complete and the resources no longer need to be locked, run the API command for unlocking the resource group. If the session used for locking is discarded, the locked resource group will be unlocked at the same time. If the session is discarded due to a session timeout, the locked resource group will also be unlocked at the same time.

Tip
  • A session timeout occurs even when an asynchronous processing API operation is being run. If you want to continue to lock the resources while an asynchronous processing API operation is being run, prevent a session timeout by taking a measure, such as periodically issuing the request that checks the job status.
  • If you want to forcibly unlock resources because a REST API client unexpectedly continues to lock the resources or the token is lost, either wait until the session times out or forcibly discard the session by using a user who belongs to the Administrator user group (built-in user group) .
  • If the locked user information (such as the role and resource group) is changed while the resource is being locked, the changes are applied to operations after the resource is unlocked.
Operation flow for running API requests by using the lock functionality

The following table describes the operation flow for running API requests by locking resource groups.

Step

Operation

Item to be specified for the Authorization header

1

Generate a session.

User ID and password

2

Lock the resource group.

The token of the session generated in step 1

3

Perform operations on the locked resource.

The token of the session generated in step 1

4

Unlock the resource group.

The token of the session generated in step 1

5

Discard the session.

The token of the session generated in step 1

Operation flow for running API requests by using the lock functionality (for remote copy)

For copy operations between storage systems (remote copy), to perform operations to change configurations of a copy group or the resources in a copy group by locking the target resources, lock the resources of both the local and remote storage systems. To lock the both resources and perform operations on the locked resources, specify the token of the session of each storage system for the Authorization header and the Remote-Authorization header. Note that the Remote-Authorization header is used only for the API commands that are used for the following object types:

  • remote-mirror-copygroups
  • remote-mirror-copypairs
  • remote-storages

The following table describes the operation flow for when the resources of both the local and remote storage systems are locked.

Step

Storage system on which operations are performed

Operation

Item to be specified for the Authorization header

1

Local storage system

Generate a session.

User ID and password for the local storage system

2

Remote storage system

Generate a session.

Specify at least 60 seconds for the timeout time of a session generated on the remote storage system.

User ID and password for the remote storage system

3

Local storage system

Lock the resource group.

The token of the session generated in step 1

4

Remote storage system

Lock the resource group.

The token of the session generated in step 2

5

Local storage system

Perform operations on a copy group or the resources in a copy group.

The token of the session generated in step 1

Also, specify the token of the session generated in step 2 for the Remote-Authorization header.

6

Local storage system

Unlock the resource group.

The token of the session generated in step 1

7

Remote storage system

Unlock the resource group.

The token of the session generated in step 2

8

Local storage system

Discard the session.

The token of the session generated in step 1

9

Remote storage system

Discard the session.

The token of the session generated in step 2

Tip

If creation of a remote copy pair is run, the initial copy processing for creating a pair on the storage system might take a long time. In this case, if resources are locked until the pair is created, other clients cannot use the resources of the resource group for a long time. Resources do not need to be locked by the REST API after the storage system accepts the request that creates a pair. Therefore, when you create a remote pair, we recommend that you unlock the resources after the job status is changed to "StorageAccepted".