Skip to main content

Asynchronous operations

By default, a create, edit, or delete request waits for the operation to finish and returns the outcome. That's the simplest way to script a sequence of steps. For operations that can take a while, or when you want to start several at once, you can run an operation in the background instead: the request returns straight away, and you check on the operation afterward.

Starting an operation in the background

Add async=true to the query string of a POST, PUT, or DELETE request:

POST /applications/volumes/create?async=true

The request returns as soon as the operation has been started. The response has the usual envelope (see Requests and responses), and Result describes the job that was started, including its Id. Keep that ID: it's how you check on the job.

GET endpoints only read data, so they're always synchronous and have no async parameter.

Checking on a job

Every operation is tracked as a configuration, with a state. To check on the jobs your session started, call:

GET /configurations/session/list?jobids=<id>

The response lists a configuration for each job, with these fields among others:

Field Description
Id The job ID.
State Pending or Running while the job is in progress; Success or Failed when it has finished (Unknown is also possible).
Description What the job is doing.
StartTime, EndTime When the job started and, once finished, when it ended.
Message Any message the operation produced.
Async true for jobs started with async=true.

Poll until State is Success or Failed. A few seconds between checks is plenty for most operations.

The endpoint also takes these optional query parameters: jobids (repeat it to check several jobs at once), async or sync (show only background or only waited-for jobs), top (limit the number of results), and descendingOrder (newest first). See Configurations and settings in the Endpoint Reference.

For jobs that belong to other sessions, or to look back after you've logged out, use the system-wide history instead:

GET /configurations/list

It takes filters for the state (pending, inProgress, success, failure), top, and descendingOrder. The same history is shown in the web interface under Monitoring > Configurations; see Configurations.

A typical sequence

  1. POST /login to get a token.
  2. Start one or more operations with async=true, noting each job's Id.
  3. Poll GET /configurations/session/list?jobids=<id> until each job's State is Success or Failed.
  4. If a job failed, read its Message, fix the cause, and run the operation again.
  5. DELETE /logout.

Examples shows this in curl, PowerShell, and Python.

Next: Examples — complete walkthroughs in curl, PowerShell, and Python.

No comments to display