Tracking asynchronous operations

There are a number of APIs that are operated asynchronously. Asynchronous APIs return a task (or list of tasks) with a self link to the created resource and operation that uniquely identifies this request. This URI can be polled to check if the operation has succeeded, failed or is in progress.

If the request was successful and the asynchronous operation is being processed, the service returns status code 202 (Accepted). Note that this status code does not indicate whether the operation itself has been processed successfully, but only that the request has been received by the service.

Task response contains status information which is set to pending initially. Polling on task URI can be done until the returned state is error or ready. If the operation failed, response will include additional error information. If there are multiple tasks, each task URI can be polled to determine that particular operation status.

Note: An asynchronous operation may take an unspecified amount of time to complete. You application should poll every 10 seconds to see when the operation is complete.

GET {resource_URL}/tasks

Returns a list of tasks created by asynchronous operations. The resource_URL is the path to the resource. For example:

GET /block/volume/tasks

GET {resource_URL}/tasks/{op_id}

Returns detailed information about a task. The resource_URL is the path to the resource. The op_id is the operation ID returned from an asynchronous API. For example:

GET /block/volume/tasks/{op_id}

Example Asynchronous API

This section shows an example of how to track asynchronous operation status.

Request

POST /block/volumes

Request body

    <volume_create>
	    <name>Sample_Volume</name>
	    <size>1073741824</size>
	    <count>1</count>
	    <vpool>{vpool_id}</vpool>
	    <varray>{varray_id}</varray>
	    <project>{project_id}</project>
    </volume_create>

Response

202

Response body

    <tasks>
	<task>
		<resource>
		<name>Sample_Volume</name>
		<id>urn:storageos:Volume:5ba5b8d8-a0ca-4827-84f9-c1fef57733f5:</id>
		<link rel="self" href="/block/volumes/urn:storageos:Volume:5ba5b8d8-a0ca-4827-84f9-c1fef57733f5:" />
		</resource>
		<state>pending</state>
		<start_time>1379398608574</start_time>
		<op_id>265cf333-76a1-4129-903e-fac63f9b4adc</op_id>
		<link rel="self" href="/block/volumes/urn:storageos:Volume:5ba5b8d8-a0ca-4827-84f9-c1fef57733f5:/tasks/265cf333-76a1-4129-903e-fac63f9b4adc" />
 	</task>
    </tasks>