Skip to main content

Dell Unity™ Family Unisphere® Management REST API Programmer's Guide

PDF

Working with asynchronous requests

By default, all REST API requests are synchronous, which means that the client/server connection stays open until the request completes and the response is returned.

Alternatively, you can make any active management request (one that changes the system rather than just querying it) into an asynchronous request by appending a timeout parameter to the HTTP request header. Asynchronous requests are more reliable than synchronous requests. With an asynchronous request, you start a job, and the server returns an associated job resource instance almost immediately, if you use timeout=0. You can query the job resource instance when convenient to get the HTTP response code and response body for the request. If you create a synchronous request and the network connection is lost, or the REST client or server goes down while the request is processing, there is no way to obtain the request status.

Syntax

As the first parameter on the request URI:

?timeout=<seconds>

As a subsequent parameter on the request URI:

&timeout=<seconds>

Usage

The following considerations apply to asynchronous requests:

  • A valid asynchronous request returns a 202 Accepted HTTP status code and a minimal job resource instance in the response body.
  • Depending on the type of error, an invalid asynchronous request can either return immediately or return after the timeout with the appropriate error code in the response header and a message entity in the response body.

To view the status of an asynchronous request, retrieve data for the appropriate job resource instance. For example, if an asynchronous modify user request returns a job resource instance with an ID of N-67, you can use an instance query to retrieve the asynchronous request data from this job resource.

Example 1: Creating an asynchronous request

The following example uses the timeout request parameter on a request to modify a user instance.

Headers 
Accept: application/json
Content-Type: application/json
X-EMC-REST-CLIENT: true
EMC-CSRF-TOKEN: <token>
Request 
POST https://10.108.53.216/api/instances/user/user_1/action/modify?timeout=0
Request body 
{
  "role":"operator"
   }
Response body 
{
  "id": "N-116",
  "state": 2,
  "instanceId": "root/emc:EMC_UEM_TransactionJobLeaf%InstanceID=N-116",
  "description": "job.uisconfig.job.ModifyUser",
  "stateChangeTime": "2015-11-20T18:53:03.875Z",
  "submitTime": "2015-11-20T18:53:03.680Z",
  "estRemainTime": "00:01:40.000",
  "progressPct": 0,
  "tasks": [
    {
      "state": 0,
      "name": "job.uisconfig.job.ModifyUser"
    }
  ],
  "owner": "System",
  "clientData": "",
  "methodName": "user.modify",
  "isJobCancelable": false,
  "isJobCancelled": false
}

Example 2: Viewing an asynchronous request

The following example shows the job instance associated with the request shown above:

Headers 
Accept: application/json
X-EMC-REST-CLIENT: true
Request 
GET https://10.108.53.216/api/instances/job/N-116?fields=description,tasks
Request body
Empty.
Response body 
{
  "@base": "https://10.108.53.216/api/instances/job",
  "updated": "2015-11-20T18:59:23.635Z",
  "links": [
    {
      "rel": "self",
      "href": "/N-116"
    }
  ],
  "content": {
    "id": "N-116",
    "description": "Modify User",
    "tasks": [
      {
        "state": 2,
        "name": "job.uisconfig.job.ModifyUser172",
        "description": "Modify User",
        "messages": [
          {
            "errorCode": 0,
            "messages": [
              {
                "locale": "en_US",
                "message": "Success"
              }
            ]
          }
        ]
      }
    ]
  }
}

Rate this content

Accurate
Useful
Easy to understand
Was this article helpful?
0/3000 characters
  Please provide ratings (1-5 stars).
  Please provide ratings (1-5 stars).
  Please provide ratings (1-5 stars).
  Please select whether the article was helpful or not.
  Comments cannot contain these special characters: <>()\