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.
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.
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.
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
URL formats (excluding the base URL) |
HTTP method |
Processing method |
Operations |
/simple/v1/objects/storages |
GET |
Synchronous |
Obtains storage system information |
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 |
|
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 |
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.
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
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.
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 |
|
Password |
6 through 63 characters |
|
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
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 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.
|
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:
|
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:
|
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:
|
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.
- 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.
- 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¶meter=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:
|
hasNext |
boolean | Whether there is information that has not yet 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:
|
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:
|
status |
string |
Status of the execution results of the API function. The following values can be returned:
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:
|
- 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:
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
|
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.
Storage Administrator (View Only)
GET base-URL/simple/v1/objects/storage
Object ID
None.
Query parameters
None.
Body
None.
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.
- efficiencyDataReduction
(int)1
See HTTP status codes.
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.
Storage Administrator (View Only)
GET base-URL/simple/v1/objects/command-status/object-ID
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.
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
See HTTP status codes.
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.
Storage Administrator (System Resource Management)
DELETE base-URL/simple/v1/objects/command-status/object-ID
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.
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.
See HTTP status codes.
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