Common operations in the REST API
You can perform common REST API operations such as change, delete, generate, and get information about jobs and session. You can also manage resource locks.
Getting the version information
The following request gets information about the version of the REST API.
No role is required to run this API request.
This API request does not require authorization. Therefore, the Authorization header does not need to be specified.
GET base-URL/configuration/version
Object ID
None.
Query parameters
None.
Body
None.
Body
{ "productName": "Configuration Manager REST API", "apiVersion": "1.12.3" }
Attribute
Type
Description
productName
string
Name of the REST API
apiVersion
string
Version of the REST API
For details on the status codes of the API, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -X GET https://192.0.2.100/ConfigurationManager/configuration/version
Getting a list of storage systems
The following request gets a list of the storage systems that can be operated from the REST API. You can check information about storage systems, such as the storage device ID and the serial number of the storage system.
No role is required to run this API request.
This API request does not require authorization. Therefore, the Authorization header does not need to be specified.
GET base-URL/v1/objects/storages
Object ID
None.
Query parameters
None.
Body
None.
Body
{ "data": [ { "storageDeviceId": "886000123456", "model": "VSP G700", "serialNumber": 123456, "ctl1Ip": "192.0.2.100", "ctl2Ip": "192.0.2.101" } ] }
Attribute
Type
Description
storageDeviceId
string
Storage device ID
model
string
Model name of the storage system
serialNumber
int
Serial number of the storage system
ctl1Ip
string
IP address of controller 1 of the storage system
ctl2Ip
string
IP address of controller 2 of the storage system
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/storages
Getting information about a specific storage system
The following request gets information about the storage system for which an operation is to be performed.
Storage Administrator (View Only)
GET base-URL/v1/objects/storages/instance
Object ID
Specify a value for
instance
. For objects that have only one instance, the value ofinstance
is a fixed value (the object ID).
Query parameters
Attribute
Type
Filter Condition
detailInfoType
string
(Optional) Type of detailed information to be obtained
- version
Additional detailed information about the microcode of the storage system, controller 1, and controller 2 is obtained.
- version
Body
None.
Body
{ "storageDeviceId" : "886000123456", "model" : "VSP G700", "serialNumber" : 123456, "ctl1Ip": "192.0.10.10", "ctl2Ip": "192.0.10.11", "dkcMicroVersion" : "88-01-01/00", "communicationModes": [ { "communicationMode": "lanConnectionMode" } ], "isSecure": true }
Attribute
Type
Description
storageDeviceId
string
Storage device ID
model
string
Model name of the storage system
serialNumber
int
Serial number of the storage system
ctl1Ip
string
IP address of controller 1 of the storage system
ctl2Ip
string
IP address of controller 2 of the storage system
dkcMicroVersion
string
Microcode version of the storage system
communicationModes
object[]
Array of communication modes
The following attributes are output for the communication modes between the REST API server and the storage system:
-
communicationMode (string)
Communication mode
lanConnectionMode is displayed.
isSecure
boolean
Whether the communication between the REST API server and the storage system is secure.
The default value is true.
You can obtain detailed information about the microcode of the storage system by executing the request with version specified for the
detailInfoType
query parameter.{ "storageDeviceId": "886000123456", "model": "VSP G900", "serialNumber": 123456, "ctl1Ip" : "192.0.10.10", "ctl2Ip" : "192.0.10.11", "dkcMicroVersion": "88-01-01/82", "detailDkcMicroVersion": "88-01-01-60/82", "ctl1MicroVersion" : "88-01-01/81", "ctl2MicroVersion" : "88-01-01/81", "communicationModes": [ { "communicationMode": "lanConnectionMode" } ], "isSecure": true }
Attribute
Type
Description
detailDkcMicroVersion
string
Microcode version of the storage system
Model identification information is included.
ctl1MicroVersion
string
GUM version of the controller 1
If a failure has occurred in the GUM of controller 1, this information is not obtained.
ctl2MicroVersion
string
GUM version of the controller 2
If a failure has occurred in the GUM of controller 2, this information is not obtained.
-
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/storages/instance
Getting a list of sessions
The following request gets a list of valid sessions on the REST API server. Only a user who belongs to the Administrator user group (built-in user group) can perform this operation.
Administrator user group (built-in user group)
GET base-URL/v1/objects/sessions
Object ID
None.
Query parameters
None.
Body
None.
Body
{ "data": [ { "sessionId": 8, "userId": "rest-user", "ipAddress": "192.0.2.100", "createdTime": "2015-09-14T01:02:24Z", "lastAccessedTime": "2015-09-14T01:02:24Z" }, { "sessionId": 6, "userId": "api-user", "ipAddress": "192.0.2.100", "createdTime": "2015-09-14T00:59:58Z", "lastAccessedTime": "2015-09-14T00:59:58Z" }, { "sessionId": 5, "userId": "admin-user", "ipAddress": "192.0.2.100", "createdTime": "2015-09-14T00:59:53Z", "lastAccessedTime": "2015-09-14T00:59:53Z" } ] }
Attribute
Type
Description
sessionId
int
Session ID
userId
string
User ID that was used to generate the session
ipAddress
string
IP address of the REST API client that was used to generate the session
If the REST API client accesses the REST API server via another server, a character string consisting of the concatenated IP addresses of the client and of the server used to access the REST API server (the content of the X-Forwarded-For header received by the REST API server) will be output.
createdTime
ISO8601string
Time the session was generated
lastAccessedTime
ISO8601string
Time the session was last used
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/sessions/
Getting information about a specific session
The following request gets information about a valid session on the REST API server by specifying a session ID. For the Authorization header of the request, specify the token of the session.
Storage Administrator (View Only)
GET base-URL/v1/objects/sessions/object-ID
Object ID
Specify the value of
sessionId
that was obtained when the session was generated.Attribute
Type
Description
sessionId
int
(Required) Session ID
Query parameters
None.
Body
None.
Body
{ "token": "97c13b8082444b36bc2103026205fa64", "sessionId": 9 }
Attribute
Type
Description
sessionId
int
Session ID
token
string
Token
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/sessions/9
Generating sessions
The following request generates sessions and manages the sessions on the REST API server. A maximum of 64 sessions can be generated for each disk controller. When the number of sessions exceeds the maximum number of sessions, the HTTP status code 503 is returned. In this case, wait a while and then run the request again.
aliveTime
attribute of the sessions generated on the remote storage
system. If you specify less than 60 seconds, the session on the remote storage system might
time out, causing the execution of a request to fail.Storage Administrator (View Only)
POST base-URL/v1/objects/sessions
Object ID
None.
Query parameters
None.
Body
The following coding example specifies the time until a session timeout:
{ "aliveTime": 5 }
Attribute
Type
Description
aliveTime
long
(Optional) Session timeout value (in seconds)
Specify a value in the range from 1 to 300#.
If this attribute is omitted, 300 is assumed.
authenticationTimeout
long
(Optional) Timeout value for authentication processing (in seconds)
Specify this value if an external authentication server is being used to authenticate users.
Change the value according to the external authentication settings of the storage system.
Specify a value in the range from 1 to 900.
If this attribute is omitted, 120 is assumed.
#: There might be a delay of up to five seconds after the specified amount of time has elapsed, before the session times out.
Body
{ "token": "d7b673af189048468c5af9bcf3bbbb6f", "sessionId": 3 }
Attribute
Type
Description
sessionId
int
Session ID
An ID that is used to manage sessions.
token
string
Token
Information that is used to identify the source that issues requests as a specific user.
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -u rest-test:rest-api -X POST https://192.0.2.100/ConfigurationManager/v1/objects/sessions/ -d ""
Discarding sessions
The following request discards the sessions that are no longer required. If a session is discarded, the lock obtained in that session is unlocked at the same time. For the Authorization header of the request, specify the token for a session to be discarded.
Storage Administrator (View Only)
DELETE base-URL/v1/objects/sessions/object-ID
Object ID
Specify the value of
sessionId
that was obtained when the session was generated. A user who belongs to the Administrator user group (built-in user group) can specify the value ofsessionId
that was obtained by the processing to get information about sessions.Attribute
Type
Description
sessionId
int
(Required) Session ID
Query parameters
None.
Body
{ "force": true }
Attribute
Type
Description
force
boolean
Specify whether to force discarding of the session generated by other users, in addition to the session you generated. Only a user who belongs to the Administrator user group (built-in user group) can specify this attribute.
- true: Forces discarding of the session generated by other users, in addition to the session you generated.
- false: Forces discarding of only the session you generated.
If you omit this value, false is used.
Body
None.
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X DELETE --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/objects/sessions/1
Getting a list of job information
The following request gets a list of information about jobs that were submitted by the user from the REST API. Only a user who belongs to a user group with the Storage Administrator (System Resource Management) role can get information about all the registered jobs. Job information can be used to check APIs that were issued and to identify the cause of a problem in the storage system.
No role is required to run this API request. Only the users authenticated by the storage system can issue this API request.
GET base-URL/v1/objects/jobs
Object ID
None.
Query parameters
If no query parameters are specified, the request gets information about 100 jobs that can be referenced by the user and were submitted after the other jobs.
Parameter
Type
Filter Condition
startCreatedTime
ISO8601string
(Optional) Specify the submission start time of the jobs for which you want to get information. Specify the time in YYYY-MM-DDThh:mm:ssZ format.
The request gets information about jobs that were submitted on and after the specified time.
endCreatedTime
ISO8601string
(Optional) Specify the submission end time of the jobs for which you want to get information. Specify the time in YYYY-MM-DDThh:mm:ssZ format.
The request gets information about jobs that were submitted before the specified time.
count
int
(Optional) Specify a number from 1 to 100 for the number of jobs for which you want to get information.
The specified number is the maximum number of jobs for which information will be obtained.
If this is omitted, 100 is assumed.
status
string
(Optional) Specify one of the following values for the status of the jobs for which information is to be obtained.
- Initializing: The jobs are being initialized.
If you also need to specify a value for "state", you must specify Queued for "state".
- Running: The jobs are running.
If you also need to specify a value for "state", you must specify Started for "state".
- Completed: The jobs have been completed.
If you also need to specify a value for "state", you must specify Succeeded, Failed, or Unknown for "state".
state
string
(Optional) Specify one of the following values for the status (state) of the jobs for which information is to be obtained.
- Queued: The jobs have been queued.
- Started: The jobs have been started.
- Succeeded: The jobs finished successfully.
- Failed: The jobs failed.
- Unknown: The state of the jobs is unknown.
The following example gets information about a maximum of 30 jobs that ended normally and were submitted after other jobs during the period from "2015/05/01 08:00:00" to "2015/05/31 23:59:59".
?startCreatedTime=2015-05-01T08:00:00Z&endCreatedTime=2015-05-31T23:59:59Z&count=30&state=Succeeded
- Initializing: The jobs are being initialized.
Body
None.
Body
{ "data": [ { "jobId": 2, "self": "/ConfigurationManager/v1/objects/jobs/2", "userId": "rest-test", "status": "Completed", "state": "Succeeded", "createdTime": "2015-09-14T02:08:13Z", "updatedTime": "2015-09-14T02:08:13Z", "completedTime": "2015-09-14T02:08:13Z", "request": { "requestUrl": "/ConfigurationManager/v1/services/resource-group-service/actions/lock/invoke", "requestMethod": "POST", "requestBody": { "parameters": { "waitTime": null } } }, "affectedResources": [ "/ConfigurationManager/v1/objects/resource-groups" ] }, { "jobId": 1, "self": "/ConfigurationManager/v1/objects/jobs/1", "userId": "rest-test", "status": "Completed", "state": "Failed", "createdTime": "2015-09-14T02:04:11Z", "updatedTime": "2015-09-14T02:04:12Z", "completedTime": "2015-09-14T02:04:12Z", "request": { "requestUrl": "/ConfigurationManager/v1/services/resource-group-service/actions/lock/invoke", "requestMethod": "POST", "requestBody": { "parameters": { "waitTime": null } } }, "error": { "errorSource": "/ConfigurationManager/v1/services/resource-group-service/actions/lock/invoke", "message": "An error occurred in the storage system. (message = Access denied with Lock/Unlock)", "cause": "An error occurred during execution of a CCI command.", "solution": "See the manual of the CCI and remove the cause of the error.", "solutionType": "SEE_ERROR_DETAIL", "messageId": "KART30000-E", "errorCode": { "errorCode": "EX_EACCES" } } } ] }
Attribute
Type
Description
data
object[]
Job information (job objects) created by the user from the REST API.
The maximum number of jobs for which you can get information at one time is 100.
For details on the job object schema, see the section explaining job objects.
For details on the status codes of the request for this operation, see the description on HTTP status codes.
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/jobs
Getting job information
The following request gets, at a specific timing, information about a specified job that was submitted by the user from the asynchronous API. Only a user who belongs to a user group with the Storage Administrator (System Resource Management) role can also obtain information about jobs submitted by other users. The obtained information can be used to check the job status.
No role is required to run this API request. Only the users authenticated by the storage system can issue this API request.
GET base-URL/v1/objects/jobs/object-ID
Object ID
Specify the
jobId
value obtained by getting information about the job list or the response message of the asynchronous API.Attribute
Type
Description
jobId
long
(Required) Job object ID
Query parameters
None.
Body
None.
Body
{ "jobId": 3, "self": "/ConfigurationManager/v1/objects/jobs/3", "userId": "rest-test", "status": "Completed", "state": "Succeeded", "createdTime": "2015-09-14T02:08:13Z", "updatedTime": "2015-09-14T02:08:13Z", "completedTime": "2015-09-14T02:08:13Z", "request": { "requestUrl": "/ConfigurationManager/v1/services/resource-group-service/actions/lock/invoke", "requestMethod": "POST", "requestBody": { "parameters": { "waitTime": null } } }, "affectedResources": [ "/ConfigurationManager/v1/objects/resource-groups" ] }
For details on the job object schema, see the description on job objects.
The following table describes the meaning of the status code of the request for this operation. For details on other status codes, see the section explaining HTTP status codes.
Status codes |
Message |
Description |
404 |
Not Found |
|
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X GET https://192.0.2.100/ConfigurationManager/v1/objects/jobs/3
Locking a resource group
The following request locks resources of a resource group allocated to the user who runs API requests, preventing other users from performing operations on the resources. Exclusive control by locking is performed on a session basis. To run requests on the locked resources, specify as the Authorization header the token of the session that was specified when the resources were locked.
Storage Administrator (View Only)
POST base-URL/v1/services/resource-group-service/actions/lock/invoke
Object ID
None.
Query parameters
None.
Body
{ "parameters": { "waitTime": 30 } }
Attribute
Type
Description
waitTime
int
The time that elapses before a lock timeout (in seconds)
Specify a value from 0 to 7200 for the maximum wait time that elapses before a lock timeout occurs, for cases such as when the target resource is already locked by other sessions.
If this value is omitted, 0 is specified.
Body
A job object is returned. For details on attributes other than
affectedResources
, see the description on job objects.Attribute
Description
affectedResources
URL of the resource group that obtained a lock
For details on the status codes of the request for this operation, see the description on HTTP status codes.
Status code |
Message |
Description |
503 |
Service unavailable |
The operation cannot be performed because an API operation that locks or unlocks resources is being run by using the same session. |
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST --data-binary @./InputParameters.json https://192.0.2.100/ConfigurationManager/v1/services/resource-group-service/actions/lock/invoke
Unlocking a resource group
The following request unlocks a resource group. For the Authorization header of the request for releasing the lock, specify the token of the session that got the lock.
Storage Administrator (View Only)
POST base-URL/v1/services/resource-group-service/actions/unlock/invoke
Object ID
None.
Query parameters
None.
Body
None.
Body
A job object is returned. For details on attributes other than
affectedResources
, see the section explaining job objects.Attribute
Description
affectedResources
URL of the resource group that was unlocked
For details on the status codes of the request for this operation, see the section explaining HTTP status codes.
Status code |
Message |
Description |
503 |
Service unavailable |
The operation cannot be performed because an API operation that locks or unlocks resources is being run by using the same session. |
curl -v -H "Accept:application/json" -H "Content-Type:application/json" -H "Authorization:Session d7b673af189048468c5af9bcf3bbbb6f" -X POST https://192.0.2.100/ConfigurationManager/v1/services/resource-group-service/actions/unlock/invoke -d ""