Asynchronous operations
REST API server supports asynchronous operations. Asynchronous operations are processed in two ways.
- An individual API operation needs a considerable amount of time to process, then it will be set up in an asynchronous mode. Sections for APIs that can run asynchronously provide details for this operation.
- The client program dynamically requests an asynchronous operation that contains a new custom HTTP header ( X-Async: true) .
- When the server receives a new asynchronous request, instead of actually creating, updating, or retrieving a resource, the server returns a response containing the job URI in both the response body content and location header, displaying an HTTP status value of 202 (Accepted).
- The client program is responsible for polling the job status. The client sends a request using the provided URI. When the job completes, the job status changes to FINISHED , and the response result and HTTP status code is encapsulated inside the nested response object.
Note The REST API server currently retains only 30 days of job data. After this period, the job ID and data will be deleted from the REST API server database.
job object model
| Attribute | JSON type | Data type | Description |
| createdTime | string | string | Timestamp when the asynchronous request is received by the server. |
| jobId | number | uint64 | Unique job identifier for each asynchronous request. |
| jobStatus | string | string | The job status. Possible values are:
|
| locationUri | string | string | The URI of the job used by the client program to poll to retrieve the job request status. |
| request | object | object | The object containing request information. |
| requestState | string | string | The request state of the actual API operation. Possible values are:
|
| updatedTime | string | string | The job time stamp. This value updates when job status changes. |
| response | object | object | Encapsulates the response content and its HTTP status code when the API operation completes. |
request object model
| Attribute | JSON type | Data type | Description |
| requestBodyContent | object | object | Contains the request content if available. If no content is sent in the request, this attribute will not be presented. |
| requestHttpMethod | string | string | The request http method. Possible values are:
|
| requestUri | string | string | The original URI request. |
response object model
| Attribute | JSON type | Data type | Description |
| responseBodyContent | object | object | Contains all the response content if available. |
| responseHttpStatus | number | uint | The HTTP status code when the API completes. |
Example request: Create an iSCSI logical unit in asynchronous mode
1) The client program sends a request; the server accepts the request and sends back a response.
Requestcurl -kv -H "X-Api-Key: Td5qNSpXX4.732uVwjjuN1Wgmxw7yJwL5nygQk79k6pbVg.wvMFqH2" -H "X-Async: true" https://172.27.146.60:8444/v7/storage/iscsi-logical-units -d '{"comment":"new lun", "filesystemId":"5639DE9595A600900000000000000000", "iSCSILogicalUnitId": "lun1", "path": "/lun1.iscsi", "sizeInBytes":10000000, "virtualServerId": 2}' -X POST
Response
HTTP/1.1 202 Accepted
{
"jobId" : 4,
"locationUri" : "https://172.27.146.60:8444/v7/services/jobs/4",
"jobStatus" : "RUNNING",
"requestState" : "RUNNING",
"createdTime" : "2020-04-03 10:55:23",
"updatedTime" : "2020-04-03 10:55:24",
"request" : {
"requestUri" : "https://172.27.146.60:8444/v7/storage/iscsi-logical-units",
"requestHttpMethod" : "POST",
"requestBodyContent" : {
"comment" : "new lun",
"filesystemId" : "5639DE9595A600900000000000000000",
"iSCSILogicalUnitId" : "lun1",
"path" : "/lun1.iscsi",
"sizeInBytes" : 10000000,
"virtualServerId" : 2
}
}
}
2) The client program sends a request to retrieve request status and data.
Requestcurl -vk -H "X-Api-Key: Td5qNSpXX4.732uVwjjuN1Wgmxw7yJwL5nygQk79k6pbVg.wvMFqH2" https://172.27.146.60:8444/v7/services/jobs/4
Response
HTTP/1.1 200 OK
{
"job" : {
"createdTime" : "2020-04-03 10:55:23",
"jobId" : 4,
"jobStatus" : "FINISHED",
"locationUri" : "https://172.27.146.60:8444/v7/services/jobs/4",
"request" : {
"requestBodyContent" : {
"comment" : "new lun",
"filesystemId" : "5639DE9595A600900000000000000000",
"iSCSILogicalUnitId" : "lun1",
"path" : "/lun1.iscsi",
"sizeInBytes" : 10000000,
"virtualServerId" : 2
},
"requestHttpMethod" : "POST",
"requestUri" : "https://172.27.146.60:8444/v7/storage/iscsi-logical-units"
},
"requestState" : "SUCCEEDED",
"response" : {
"responseBodyContent" : {
"iSCSILogicalUnit" : {
"comment" : "new lun",
"filesystemId" : "5639DE9595A600900000000000000000",
"iSCSILogicalUnitId" : "lun1",
"iSCSITargetIds" : [],
"isBoundToTarget" : false,
"isMounted" : false,
"objectId" : "323a3a3a6c756e313a3a3a3a3a3a303a3a3a4f49445f24232140255f56",
"path" : "/lun1.iscsi",
"precentageCreatedx100" : 0,
"sizeInBytes" : 10000000,
"virtualServerId" : 2
},
"uri" : "https://172.27.146.60:8444/v7/storage/iscsi-logical-units/323a3a3a6c756e313a3a3a3a3a3a303a3a3a4f49445f24232140255f56"
},
"responseHttpStatus" : 201
},
"updatedTime" : "2020-04-03 10:55:24"
}
}