Skip to main content

We've Moved!

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

Overview of the REST API

Review general information about API requests, such as the basic system configuration for the REST API, how to specify resources to be managed, the information needed to execute an API request, and the information that is output when an API request is executed.

In this interface, 1KB (kikobyte), 1MB (megabyte), 1GB (gigabyte),and 1TB (terabyte) are 1,000 bytes, 1,000KB, 1,000MB,and 1,000GB, respectively.

1KiB (kibibyte), 1MB (mebibyte), 1GB (gibibyte),and 1TB (tebibyte) are 1,024 bytes, 1,024KiB, 1,024MiB,and 1,024GiB, respectively.

System configuration of REST API

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

GUID-97D7CFF2-507E-462B-A33D-99396602E64E-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.

  • GUM (Gateway for Unified Management)

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

    GUM exists in each controller, controller 1 (CTL1) and controller 2 (CTL2).

  • REST API server

    This component 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 on the GUM of the storage system.

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

Requirements for SSL communications

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 is a self-signed certificate. If the API client only allows communication with the REST API server installed with a signed certificate, then 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 for your storage system.

  • 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

Roles and access permissions of users executing API requests

To use the REST API to perform operations on storage system resources, the users who execute API requests must have access permissions for all resources.

The users who execute API requests must also have the appropriate roles (execution permissions) for the target resources. For details on the roles required for executing API requests, see information about the API requests.

Before using the REST API, register the user into a user group that has the necessary roles. Users who can operate the Storage Advisor Embedded web-based user interface can issue all API requests.

Specifying resources to be managed (URL)

In the REST API, the resources to be managed must be specified in URL format.

To specify resources to be managed, specify the URL in the following format:

protocol://host:port/application/version/domain
  • protocol

    Specify https or http.

    We recommend specifying https for security.

  • host

    Specify the GUM IP address or a host name that can be resolved. Specify either the GUM IP address for controller 1 (CTL1) or the GUM IP address for controller 2 (CTL2).

  • port

    Specify the port number to be used for communication.

    The default port number is 443 (for SSL communication) and 80 (for non-SSL communication). The port number can be omitted if the default port number is used for communications.

  • application

    Specify ConfigurationManager/simple.

Note

In this document, protocol://host:port/ConfigurationManager is indicated as a base URL.

  • version

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

  • domain

    Specify the domain. Currently only objects can be specified.

    The URL formats are as follows.

    Under objects, specify the type of object on which operations will be performed:

    • command-status
    • drives
    • external-path-groups
    • external-parity-groups
    • external-volumes
    • health-status
    • pools
    • ports
    • quorum-disks
    • servers
    • snapshot-groups
    • snapshots
    • storages
    • volumes
    • volume-server-connections

The following tables describe the URL formats supported for each object type.

Resources for the object type command-status:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/command-status/object-ID

GET

Synchronous

Obtains status information about an API function that performs asynchronous processing

DELETE

Synchronous

Clears status information about an API function that performs asynchronous processing

Resources for the object type drives:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/drives

GET

Synchronous

Obtains drive information

/simple/v1/objects/drives/actions/set-spare/invoke

POST

Asynchronous

Sets a specific spare drive

/simple/v1/objects/drives/actions/release-spare/invoke

POST

Asynchronous

Disables the settings of a specific spare drive

/simple/v1/objects/drives/object-ID

GET

Synchronous

Obtains information about a specific drive

Resources for the object type external-path-groups:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/external-path-groups

GET

Synchronous

Obtains information about external path groups

/simple/v1/objects/external-path-groups/object-ID

GET

Synchronous

Obtains information about a specific external path group

Resources for the object type external-parity-groups:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/external-parity-groups

GET

Synchronous

Obtains information about external parity groups

/simple/v1/objects/external-parity-groups/object-ID

GET

Synchronous

Obtains information about a specific external parity group

Resources for the object type external-volumes:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/external-volumes

GET

Synchronous

Obtains information about external volumes

POST

Asynchronous

Creates an external volume

/simple/v1/objects/external-volumes/object-ID

GET

Synchronous

Obtains information about a specific external volume

PATCH

Synchronous

Changes the nickname of an external volume

Resources for the object type health-status:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/health-status

GET

Synchronous

Obtains the operating status of storage resources

Resources for the object type pools:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/pools

GET

Synchronous

Obtains pool information

POST

Asynchronous

Creates a pool

/simple/v1/objects/pools/object-ID

GET

Synchronous

Obtains information about a specific pool

PATCH

Synchronous

Changes pool settings

DELETE

Asynchronous

Deletes a pool

/simple/v1/objects/pools/object-ID/actions/expand/invoke

POST

Asynchronous

Adds drives to a pool

Resources for the object type ports:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/ports

GET

Synchronous

Obtains port information

/simple/v1/objects/ports/object-ID

GET

Synchronous

Obtains information about a specific port

PATCH

Synchronous

Changes port settings

Resources for the object type quorum-disks:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/quorum-disks

GET

Synchronous

Obtains information about quorum disks

POST

Asynchronous

Registers information about a quorum disk

/simple/v1/objects/quorum-disks/object-ID

GET

Synchronous

Obtains information about a specific quorum disk

DELETE

Asynchronous

Deletes information about a quorum disk

Resources for the object type servers:
Note

These resources can only be used if the servers that use a storage system are managed by Storage Advisor Embedded.

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/servers

GET

Synchronous

Obtains server information

POST

Asynchronous

Registers a server

/simple/v1/objects/servers/object-ID

GET

Synchronous

Obtains information about a specific server

PATCH

Asynchronous

Changes server settings

DELETE

Asynchronous

Deletes server information

/simple/v1/objects/servers/object-ID/actions/add-host-groups/invoke

POST

Asynchronous

Adds host groups (iSCSI target) to a server

/simple/v1/objects/servers/object-ID/actions/sync-host-group-names/invoke

POST

Asynchronous

Synchronizes the host group name (iSCSI target name) with the server nickname

/simple/v1/objects/servers/object-ID/hbas

GET

Synchronous

Obtains information about the WWN (iSCSI name) of the HBA for the specified server

POST

Asynchronous

Adds information about the WWN (iSCSI name) of the HBA for the specified server

/simple/v1/objects/servers/object-ID/hbas/object-ID

GET

Synchronous

Obtains information about the server specified by the server ID and the WWN (iSCSI name) of the HBA

DELETE

Asynchronous

Deletes information from the server specified by the server ID and the WWN (iSCSI name) of the HBA

/simple/v1/objects/servers/object-ID/paths

GET

Synchronous

Obtains server path information

POST

Asynchronous

Adds path information to a server

/simple/v1/objects/servers/object-ID/paths/object-ID

GET

Synchronous

Obtains path information for a specific server

DELETE

Asynchronous

Deletes path information from the server

/simple/v1/objects/servers/object-ID/target-iscsi-ports

GET

Synchronous

Obtains information about iSCSI targets

/simple/v1/objects/servers/object-ID/target-iscsi-ports/object-ID

GET

Synchronous

Obtains information about a specific iSCSI target

PATCH

Asynchronous

Changes the settings of an iSCSI target

Resources for the object type snapshot-groups:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/snapshot-groups

GET

Synchronous

Obtains snapshot group information

/simple/v1/objects/snapshot-groups/object-ID

GET

Synchronous

Obtains information about a specific snapshot group

DELETE

Asynchronous

Deletes a snapshot group

Resources for the object type snapshots:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/snapshots

GET

Synchronous

Obtains snapshot information

POST

Asynchronous

Creates a snapshot

/simple/v1/objects/snapshots/object-ID

GET

Synchronous

Obtains information about a specific snapshot

DELETE

Asynchronous

Deletes a snapshot

/simple/v1/objects/snapshots/object-ID,object-ID/actions/map/invoke

POST

Asynchronous

Maps a snapshot

/simple/v1/objects/snapshots/object-ID,object-ID/actions/restore/invoke

POST

Asynchronous

Restores a snapshot

Resources for the object type storages:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/storages

GET

Synchronous

Obtains storage system information

Resources for the object type volumes:

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/volumes

GET

Synchronous

Obtains volume information

POST

Asynchronous

Creates a volume

/simple/v1/objects/volumes/object-ID

GET

Synchronous

Obtains information about a specific volume

PATCH

  • Synchronous
  • Asynchronous

Changes volume settings

DELETE

Asynchronous

Deletes a volume

/simple/v1/objects/volumes/object-ID/actions/expand/invoke

POST

Synchronous

Expands the capacity of a volume

/simple/v1/objects/volumes/object-ID/qos-setting

GET

Synchronous

Obtains the QoS settings of a specific volume

PATCH

Asynchronous

Edits the QoS settings of a volume

Resources for the object type volume-server-connections:
Note

These resources can only be used if the servers that use a storage system are managed by Storage Advisor Embedded.

URL formats (excluding the base URL)

HTTP method

Processing method

Operations

/simple/v1/objects/volume-server-connections

GET

Synchronous

Obtains information about the connection between a volume and a server

POST

Asynchronous

Connects a volume and a server

/simple/v1/objects/volume-server-connections/object-ID

GET

Synchronous

Obtains information about the connection between a volume and a specific server

DELETE

Asynchronous

Disconnects a volume and a specific server

The REST API has the following two processing methods:

  • Synchronous processing

    The processing results are returned as the response.

  • Asynchronous processing

    The object information and the HTTP status code (202), which indicates that the processing has been accepted, are returned as the response.

Note

A maximum of 16 requests can be executed at the same time.

Specifying an object ID

An object ID is used to uniquely identify a resource.

An object ID is used when specifying a specific resource in a URL. To specify an object ID, execute the GET operation and then obtain the object ID from the execution results.

  • Example: If the object ID of a volume is 100

    volumes/100
Note

When the GET operation is performed to obtain an object ID, the REST API server sometimes returns a value encoded according to RFC 3986, as the value of the attribute obtained by the GET operation. To use the object ID obtained by performing the GET operation in a request of another operation, use the object ID without decoding it.

Supported HTTP methods

Specify operations to be performed on resources in the HTTP method.

The REST API supports the following HTTP methods.

HTTP method

Description

GET

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

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

When information about multiple objects is obtained, the information is not sorted by object ID (id), such as the pool ID or volume ID. For this reason, filter the information to be obtained by specifying query parameters. Alternatively, if you know the object IDs of the objects for which you want to get information, run the API request for obtaining information about specific objects.

POST

This method performs operations such as creating, adding, or expanding objects.

For example, this method can create pools.

PATCH

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

For example, this method can change the pool threshold.

DELETE

This method deletes objects.

For example, this method can delete pools.

The methods that can be used vary depending on the objects. For details, see the descriptions for each API function.

User authentication

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

Authentication by 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 characters in the following table for the user ID and password.

Item

Number of characters

Specifiable characters

User ID

1 through 63 characters

  • Alphanumeric characters
  • The following symbols:

    Exclamation mark (!), hash mark (#), dollar sign ($), percent sign (%), ampersand (&), single quotation mark ('), asterisk (*), plus sign (+), hyphen (-), period (.), forward slash (/), equal sign (=), question mark (?), at sign (@), caret (^), underscore (_), grave accent mark (`), left curly bracket ({), vertical bar (|), right curly bracket (}), tilde (~)

Password

6 through 63 characters

  • Alphanumeric characters
  • ASCII symbols which can be keyed in except space:

    Exclamation mark (!), quotation mark ("), hash mark (#), dollar sign ($), percent sign (%), ampersand (&), single quotation mark ('), left parenthesis ((), right parenthesis ()), asterisk (*), plus sign (+), comma (,), hyphen (-), period (.), forward slash (/), colon (:), semicolon (;), left angle bracket (<), equal sign (=), right angle bracket (>), question mark (?), at sign (@), left square bracket ([), back slash (\), right square bracket (]), caret (^), underscore (_), grave accent mark (`), left curly bracket ({), vertical bar (|), right curly bracket (}), tilde (~)

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

In the Authorization header, specify the authentication information for the session in the following format:

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 b74777a3f9f04ea8bd8f09847fac48d3

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.

Request line:

POST base-URL/v1/objects/sessions

Response message:

{
  "token": "b74777a3f9f04ea8bd8f09847fac48d3",
  "sessionId": 3
}

Request headers

Request headers are request messages sent from REST API clients to the REST API server.

The following table lists the request headers supported by the REST API.

Header

Category

Description

Accept

Optional

Specifies the media type of the response.

Specifiable value: */* (json)

Default value: */* (json)

Accept-Language

Optional

Specifies the language of the messages to be received by the client.

Specify ja to set the language to Japanese. If any language other than Japanese is specified, or if this header is omitted, the language will be set to English (en).

Content-Type

Optional

Specifies the media type of the request body.

Specifiable value: 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.

Specifiable value: Specify the header, in bytes.

Default value: None.

Authorization

Required

Specifies the authorization method and authorization credentials.

Specify the header in one of the following formats:

  • If a session is to be generated:

    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.

  • If a session is not to be generated:

    Session token

    When the session was generated:

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

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

Response headers

The response headers are response messages from the REST API server to REST API clients.

The following table describes the response headers returned by the REST API server.

Header

Description

Content-Type

Indicates the media type of the response data.

Default: application/json;charset=UTF-8

Content-Length

Indicates the size of the response data.

If the size of the response data is large, instead of this header, Transfer-Encoding: chunked is returned, indicating that the response data has been divided and then transferred.

Transfer-Encoding

Indicates the encoding format used when the response data was transferred.

When a large amount of response data is divided and then transferred, chunked is returned.

Retry-After

Indicates the recommended wait time (in seconds) before the request can be retried.

When the HTTP status code 503 is returned, this header is sometimes set.

WWW-Authenticate

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

  • Default:

    • Authentication by using a user ID and password

      Basic realm="Block storage"

    • Authentication by using a session

      Session realm="Block storage"

HTTP status codes

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

HTTP status codes

Description

200

OK

The request was processed correctly.

202

Accepted

The request for asynchronous processing was accepted.

400

Bad Request

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

401

Unauthorized

The Authorization header is not specified in the request header. Alternatively, authentication by using the information specified in the Authorization header fails.

403

Forbidden

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

404

Not Found

The resource specified by the URL could not be found. Alternatively, there are no resources for the specified URL.

406

Not acceptable

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

415

Unsupported Media Type

The specified media type is not supported.

500

Internal Server Error

An internal error occurred on the server. Only the most critical error is returned.

If an API function for operating multiple resources is run, and if partial information is obtained or if part of the operation is successful, the following attribute appears:

partialSuccessResponses

The displayed content differs depending on the type of HTTP method that was used:

  • If the GET method was used:

    The obtained information (data object) appears.

  • If the POST method was used:

    The execution results (statusResource) appear.

503

Service Unavailable

Indicates that the service is temporarily unavailable because it is busy or under maintenance. Only the most critical error is returned.

If the response header includes Retry-After, wait for the period of time indicated by the return value (the recommended wait time, given in seconds), and then run the request again.

If an API function for operating multiple resources is run, and if partial information is obtained or if part of the operation is successful, the following attribute appears:

partialSuccessResponses

The displayed content differs depending on the type of HTTP method that was used:

  • If the GET method was used:

    The obtained information (data object) appears.

  • If the POST method was used:

    The execution results (statusResource) appear.

504

Gateway Timeout

No response was received from the device in the allotted time. Only the most critical error is returned.

If an API function for operating multiple resources is run, and if partial information is obtained or if part of the operation is successful, the following attribute appears:

partialSuccessResponses

The displayed content differs depending on the type of HTTP method that was used:

  • If the GET method was used:

    The obtained information (data object) appears.

  • If the POST method was used:

    The execution results (statusResource) appear.

Request and response formats

JSON format is used for creating or adding resources (POST), for specifying the attribute value when changing resources (PATCH), and for getting the results of resource information (GET).

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

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

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: "DKR5D-J900SS"

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: "2017-09-30T09:27:35Z"

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

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

  • 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

Other than the preceding

200

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

Asynchronous processing

All

202

commandStatus 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 attributes are displayed along with the data object.

Attribute

Data type

Description

count

int

Number of objects

totalCount

int

Total number of data items in the storage system

This attribute appears when one of the following API requests is executed:

  • Getting volume information
  • Getting information about the connections between volumes and servers
  • Getting external volume information
  • Getting information about external parity groups
  • Getting information about external path groups
  • Getting snapshot information
  • Getting information about a specific snapshot group

hasNext

boolean

Whether there is information that has not yet been obtained

  • true: Some information has not yet been obtained.
  • false: All information has been obtained.

If there is information that has not yet been obtained, filter the information to be obtained by specifying query parameters, or obtain the IDs (for example, volume IDs or snapshot IDs) that are larger than the largest ID in the information that is already obtained by splitting the IDs to be collected into groups and executing the API function multiple times.

This attribute appears when one of the following API requests is executed:

  • Getting volume information
  • Getting information about the connections between volumes and servers
  • Getting external volume information
  • Getting information about external parity groups
  • Getting information about external path groups
  • Getting snapshot information
  • Getting information about a specific snapshot group

The following shows an example of a data object:

{
  "data": [
    {
      "id": 100,
      "nickname": "JH-26216_DP",
      "poolId": 63,
      "poolName": "NASOS",
      "totalCapacity": 1024,
      "freeCapacity": 982,
      "numberOfConnectingServers": 2,
      "numberOfSnapshots": 2
    },
    {
      "id": 101,
      "nickname": "JH-26216_DP",
      "poolId": 63,
      "poolName": "NASOS",
      "totalCapacity": 1024,
      "freeCapacity": 1024,
      "numberOfConnectingServers": 2,
      "numberOfSnapshots": 2
    }
  ],
  "count": 2,
  "totalCount": 2,
  "hasNext": false
}

commandStatus object

A commandStatus object is the object of API status information that is returned when an API request for asynchronous processing is issued.

The following table explains the schema of a commandStatus object.

Attribute

Data type

Description

id

int

ID used for inquiry when the API function for asynchronous processing was run.

progress

string

Progress of the API function:

The following values can be returned:

  • unexecuted: The API function has not been run.
  • processing: The API function is running.
  • completed: The API function has completed.

status

string

Status of the execution results of the API function.

The following values can be returned:

  • normal: The API function finished successfully.
  • error: The API function failed.

This attribute appears only if the execution of the API function has completed.

affectedResources

string[]

URL used to access the resource targeted by the operation.

If one API function request performs operations on multiple resources, the URLs of all those resources are returned. If an API function failed, only the URLs of the resources for which processing is confirmed as 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 was deleted successfully.

This attribute appears if the execution of the API function finished successfully.

error

Error Object

Object that retains error information.

This attribute appears if the execution of the API function failed.

operationDetails

object[]

Details about a resource targeted by the operation.

This information appears when an operation is performed for the resource indicated by the resource type:

  • operationType (string)

    The type of the operation performed for the resource:

    • CREATE: The resource has been created.
    • UPDATE: The resource has been updated.
    • DELETE: The resource has been deleted.
  • resourceType (string)

    The resource type of a resource that was created, updated, or deleted:

    • CommandStatus: A resource related to status information about the API function that performs asynchronous processing
    • Pool: A resource related to pools
    • Port: A resource related to ports
    • Server: A resource related to servers
    • Snapshot: A resource related to snapshots
    • Volume: A resource related to volumes
    • VolumeServerConnection: A resource related to connections between volumes and servers
    • ExternalVolume: A resource related to external volumes
    • QuorumDisk: A resource related to quorum disk
  • resourceId (string)

    The resource ID of a resource that was created, updated, or deleted

Note
  • A maximum of 65,280 items of object information can be retained. If the number of items of API information exceeds 65,280, delete the object information by running the API that deletes the API status information in asynchronous processing.
  • The object information is deleted even if the user logs out from the session.

Example of a commandStatus object when the API function starts running:

{
  "id": 1,
  "progress": "processing"
}

Example of a commandStatus object when the API function ends successfully:

{
  "id": 2,
  "progress": "completed",
  "status": "normal",
  "affectedResources": [
    "/ConfigurationManager/simple/v1/objects/volumes/100"
  ],
  "operationDetails": [
    {
      "operationType": "CREATE",
      "resourceType": "Volume",
      "resourceId": "100"
    }
  ]
}

Example of a commandStatus object when the API function failed:

{
  "id": 3,
  "progress": "completed",
  "status": "error",
  "errorResource": "/ConfigurationManager/simple/v1/objects/pools/63",
  "errorCode": {
    "SSB1": "2e11",
    "SSB2": "001f"
  },
  "errorMessage": "Snapshot or volume exists. Operation could not be completed.",
  "operationDetails": [
    {
      "operationType": "DELETE",
      "resourceType": "Pool",
      "resourceId": "63"
    }
  ]
}

Error object

The following describes the error object that is returned together with an HTTP status code if an error occurs during the processing of a request.

The following table explains the schema of an error object.

Attribute

Data type

Description

errorSource

string

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

errorCode

string

Error code from the storage system

A value is returned only if an error occurs in the storage system.

The error codes are as follows:

  • SSB1 code
  • SSB2 code

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

partialSuccessResponses

string

An error occurred, but the result is returned if the information is partially obtained or if the processing is partially successful.

The following is an example of an error object when an error occurs in a storage system:

{
  "errorSource": "/ConfigurationManager/simple/v1/objects/volumes/100/actions/expand/invoke",
  "messageId": "KART70000-E",
  "message": "The specified volume is being used by another program product, or format in progress. Operation could not be completed. Wait for a while and try again. Confirm the volume is not in use by other program product.",
  "errorCode": {
    "SSB1": "B96B",
    "SSB2": "AF2E"
  }
}

The following table shows the schema of an error object when some information is obtained even though an error has occurred, or when only a part of the operation is complete.

Attribute

Data type

Description

errorResponses

object[]

Detailed information about the error object

  • errorSource (string)

    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

  • errorCode (string)

    Error code from the storage system

    A value is returned only if an error occurs in the storage system.

    • SSB1 code
    • SSB2 code

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

partialSuccessResponses

object[]

An error occurred, but the result is returned if the information is partially obtained or if the processing is partially successful.

If all of the processing fails, an empty array might be returned.

The following is an example of when an error occurs in a storage system but the processing is partially successful:

{
  "errorResponses": [
    {
      "errorSource": "/ConfigurationManager/simple/v1/objects/snapshots",
      "messageId": "KART70000-E",
      "message": "The specified volume does not exist. Check the parameter and try again. If this problem occurs repeatedly, contact customer support.",
      "errorCode": {
        "SSB1": "2E20",
        "SSB2": "0000"
      }
    }
  ],
  "partialSuccessResponses": [
    {
      "statusResource": "/ConfigurationManager/simple/v1/objects/command-status/3"
    }
  ]
}

Getting information about a storage system

The following request obtains information about a storage system.

Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/simple/v1/objects/storage
Request message
  • Object ID

    None.

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    Attribute

    Type

    Description

    modelName

    string

    Model name of the storage system

    serial

    string

    Serial number of the storage system

    nickname

    string

    Nickname of the storage system

    numberOfTotalVolumes

    int

    Number of created volumes

    numberOfFreeDrives

    int

    Number of free drives

    numberOfTotalServers

    int

    Number of servers managed by Storage Advisor Embedded

    totalPhysicalCapacity

    long

    Capacity of data that can be stored in the data drives of the storage system (MiB)

    totalPoolCapacity

    long

    Total capacity of the pools managed by Storage Advisor Embedded (MiB)

    usedPoolCapacity

    long

    Total used capacity of the pools managed by Storage Advisor Embedded (MiB)

    freePoolCapacity

    long

    Total free capacity of the pools managed by Storage Advisor Embedded (MiB)

    totalPoolCapacityWithTiPool

    long

    Total capacity of the pools in the storage system (MiB)

    usedPoolCapacityWithTiPool

    long

    Total used capacity of the pools in the storage system (MiB)

    freePoolCapacityWithTiPool

    long

    Total free capacity of the pools in the storage system (MiB)

    savingEffects

    object

    Information about the capacity (amount and percentage) saved throughout the storage system by the capacity saving and accelerated compression:

    • efficiencyDataReduction (int)1

      Percentage of all the data managed by Storage Advisor Embedded saved by using the capacity saving (deduplication and compression)

      The value before reduction appears. This value is calculated under the assumption that the value after reduction is 100.

      Example: If the value before reduction is 105 and the value after reduction is 100, "efficiencyDataReduction": 105 appears.

      You can convert it a ratio by dividing it by 100. Example: 105 / 100 = 1.05:1.

      If -1 appears, this value is invalid. Invalid value -1 is returned in case of that there is no data subject to reduction.

    • preCapacityDataReduction (long)1

      Capacity of all the data managed by Storage Advisor Embedded before reduction by using the capacity saving (deduplication and compression) (MiB)

    • postCapacityDataReduction (long)1

      Capacity of all the data managed by Storage Advisor Embedded after reduction by using the capacity saving (deduplication and compression) (MiB)

    • efficiencyFmdSaving (int)

      Percentage of the entire storage system capacity saved by using the accelerated compression

      The value before reduction appears. This value is calculated under the assumption that the value after reduction is 100.

      Example: If the value before reduction is 105 and the value after reduction is 100, "efficiencyFmdSaving": 105 appears.

      You can convert it a ratio by dividing it by 100. Example: 105 / 100 = 1.05:1.

      If -1 appears, this value is invalid. Invalid value -1 is returned in case of that there is no data subject to reduction.

    • preCapacityFmdSaving (long)

      Entire storage system capacity before reduction by using the accelerated compression (MiB)

      If the invalid value -1 appears for the attribute efficiencyFmdSaving, 0 appears for this attribute.

    • postCapacityFmdSaving (long)

      Entire storage system capacity after reduction by using the accelerated compression (MiB)

      If the invalid value -1 appears for the attribute efficiencyFmdSaving, 0 appears for this attribute.

    • isTotalEfficiencySupport (boolean)

      Whether the saving efficiency for consumption of capacity (referred hereafter to as total efficiency) by using the function for improving the usage efficiency of the storage system (the capacity saving (deduplication and compression), the accelerated compression, snapshots, and Dynamic Provisioning) is supported

      • true: Supported
      • false: Not supported
    • totalEfficiencyStatus (string)

      Status of the total efficiency for the entire storage system

      • Valid: Valid
      • NotSupported: Not supported
      • CalculationInProgress: Being calculated
      • NoTargetData: No data to be calculated
      • Unknown: Unknown
    • dataReductionWithoutSystemDataStatus (string)

      Status of the entire storage system capacity saved by using the capacity saving (deduplication and compression) and the accelerated compression

      • Valid: Valid
      • NotSupported: Not supported
      • CalculationInProgress: Not calculated yet
      • NoTargetData: No data to be calculated
      • Unknown: Unknown
    • totalEfficiency (long)2

      Percentage of the total efficiency for the entire storage system

      The value before reduction appears. This value is calculated under the assumption that the value after reduction is 100.

      Example: If the value before reduction is 529652 and the value after reduction is 100, "totalEfficiency": 529652 appears.

      After a volume is created from a pool and before data is written to the volume, the maximum value (9223372036854775807) appears.

      By checking the attribute calculationStartTime or calculationEndTime, you can check the date and time when calculation processing started or finished.

      In the following cases, -1 appears, to indicate an invalid value.

      • The value of the attribute isTotalEfficiencySupport is false.
      • The value of the attribute totalEfficiencyStatus is NotSupported, CalculationInProgress, or NoTargetData.
    • dataReductionWithoutSystemData (long)2

      Percentage of the entire storage system capacity saved by using the capacity saving (deduplication and compression) and the accelerated compression

      The value before reduction appears. This value is calculated under the assumption that the value after reduction is 100.

      Example: If the value before reduction is 138 and the value after reduction is 100, "dataReductionWithoutSystemData" : 138 appears.

      By checking the attribute calculationStartTime or calculationEndTime, you can check the date and time when calculation processing started or finished.

      In the following cases, -1 appears, to indicate an invalid value.

      • The value of the attribute isTotalEfficiencySupport is false.
      • The value of the attribute dataReductionWithoutSystemDataStatus is NotSupported, CalculationInProgress, or NoTargetData.
    • preCapacityDataReductionWithoutSystemData (long)2

      Entire storage system capacity before reduction by using the capacity saving (deduplication and compression) (MiB)

      If the value of the attribute isTotalEfficiencySupport is false, -1 appears, to indicate an invalid value.

    • postCapacityDataReductionWithoutSystemData (long)2

      Entire storage system capacity after reduction by using the capacity saving (deduplication and compression) (MiB)

      If the value of the attribute isTotalEfficiencySupport is false, -1 appears, to indicate an invalid value.

    • calculationStartTime (ISO8601string)

      The date and time (UTC) when calculation processing started appears in the following format: YYYY-MM-DDThh:mm:ssZ.

    • calculationEndTime (ISO8601string)

      The date and time (UTC) when calculation processing finished appears in the following format: YYYY-MM-DDThh:mm:ssZ.

    gumVersion

    string

    GUM version

    dkcMicroVersion

    string

    Microcode version of the storage system

    warningLedStatus

    string

    Status of failures in the storage system:

    • OFF: The status is normal.
    • ON: A failure has occurred.
    • BLINK: An unidentified SIM exists.
    • Unknown: Unknown

    ipAddressIpv4Ctl1

    string

    IP address for IPv4 on controller 1 (CTL1)

    ipAddressIpv4Ctl2

    string

    IP address for IPv4 on controller 2 (CTL2)

    ipAddressIpv6Ctl1

    string

    IP address for IPv6 on controller 1 (CTL1)

    ipAddressIpv6Ctl2

    string

    IP address for IPv6 on controller 2 (CTL2)

    1 The capacity after reduction is calculated based on a value that includes metadata and garbage data generated by the storage system, in addition to user data. For this reason, the value after reduction is sometimes greater than the value before reduction.

    2 The capacity after reduction does not include metadata and garbage data generated by the storage system.

Status codes

See HTTP status codes.

Coding example

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3f9f04ea8bd8f09847fac48d3" -X GET https://192.0.2.100/ConfigurationManager/simple/v1/objects/storage

Getting status information about an API function that performs asynchronous processing

The following request obtains the status information about an API function that performs asynchronous processing. For the Authorization header of the request, specify the token of the session that was used when an API function that performs asynchronous processing was run.

Execution permission

Storage Administrator (View Only)

Request line

GET base-URL/simple/v1/objects/command-status/object-ID
Request message
  • Object ID

    Specify the numerical value displayed at the end of the URL for statusResource that was returned when an API function for asynchronous processing was run.

    The following is an example of a returned statusResource:

    "statusResource": "/ConfigurationManager/simple/v1/objects/command-status/3"

    Attribute

    Type

    Description

    id

    int

    (Required) The ID used to obtain the execution results of the API function that performs asynchronous processing.

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    Example of a response message when the API function that creates a volume is run:

    {
      "id": 2,
      "progress": "completed",
      "status": "normal",
      "affectedResources": [
        "/ConfigurationManager/simple/v1/objects/volumes/100"
      ],
      "operationDetails": [
        {
          "operationType": "CREATE",
          "resourceType": "Volume",
          "resourceId": "100"
        }
      ]
    }

    Example of a response message when the API function that deletes a pool fails:

    {
      "id": 3,
      "progress": "completed",
      "status": "error",
      "errorResource": "/ConfigurationManager/simple/v1/objects/pools/63",
      "errorCode": {
        "SSB1": "2e11",
        "SSB2": "001f"
      },
      "errorMessage": "Snapshot or volume exists. Operation could not be completed.",
      "operationDetails": [
        {
          "operationType": "DELETE",
          "resourceType": "Pool",
          "resourceId": "63"
        }
      ]
    }

    Attribute

    Type

    Description

    id

    int

    ID used for inquiry when the API function for asynchronous processing was run.

    status

    string

    Status of the execution results of the API function:

    • normal: The API function finished successfully.
    • error: The API function failed.

    This attribute appears only if the execution of the API function has completed.

    affectedResources

    string[]

    List of URLs used to access the resource targeted by the operation.

    If one API function request performs operations on multiple resources, the URLs of all of those resources are returned. If an API function failed, only the URLs of the resources for which processing is confirmed as 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 was deleted successfully.

    This attribute appears if the execution of the API function finished successfully.

    errorResource

    string

    URL where the error occurs.

    This attribute appears if the execution of the API function failed.

    errorCode

    object

    Error code from the storage system.

    A value is returned only if an error occurs in the storage system.

    The error codes are as follows:

    • SSB1 code
    • SSB2 code

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

    This attribute appears if the execution of the API function failed.

    errorMessage

    string

    Content of the error message.

    This attribute appears if the execution of the API function failed.

    operationDetails

    object[]

    Details about a resource targeted by the operation

    This information appears when an operation is performed for the resource indicated by the resource type:

    • operationType (string)

      The type of the operation performed for the resource

      • CREATE: The resource has been created.
      • UPDATE: The resource has been updated.
      • DELETE: The resource has been deleted.
    • resourceType (string)

      The resource type of a resource that was created, updated, or deleted

      • CommandStatus: A resource related to status information about the API function that performs asynchronous processing
      • Pool: A resource related to pools
      • Port: A resource related to ports
      • Server: A resource related to servers
      • Snapshot: A resource related to snapshots
      • Volume: A resource related to volumes
      • VolumeServerConnection: A resource related to connections between volumes and servers
      • ExternalVolume: A resource related to external volumes
      • QuorumDisk: A resource related to quorum disk
    • resourceId (string)

      The resource ID of a resource that was created, updated, or deleted

Status codes

See HTTP status codes.

Coding example

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3f9f04ea8bd8f09847fac48d3" -X GET https://192.0.2.100/ConfigurationManager/simple/v1/objects/command-status/3

Deleting status information about an API function that performs asynchronous processing

The following request deletes status information about an API function that performs asynchronous processing.

Execution permission

Storage Administrator (System Resource Management)

Request line

DELETE base-URL/simple/v1/objects/command-status/object-ID
Request message
  • Object ID

    Specify the numerical value displayed at the end of the URL for statusResource that was returned when an API function for asynchronous processing was run.

    The following is an example of a returned statusResource:

    "statusResource": "/ConfigurationManager/simple/v1/objects/command-status/3"

    Attribute

    Type

    Description

    id

    int

    (Required) The ID used to obtain the execution results of the API function that performs asynchronous processing.

  • Query parameters

    None.

  • Body

    None.

Response message
  • Body

    Attribute

    Type

    Description

    affectedResources

    string[]

    List of URLs for referencing the deleted status information of the API

    operationDetails

    object[]

    Details about a resource for which the status information was deleted

    For details, see the description of the operationDetails attribute of the commandStatus object.

Status codes

See HTTP status codes.

Coding example

curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session b74777a3f9f04ea8bd8f09847fac48d3" -X DELETE https://192.0.2.100/ConfigurationManager/simple/v1/objects/command-status/3

 

  • Was this article helpful?