Synchronous and Asynchronous Calls


CloudCenter Suite APIs supports both synchronous and asynchronous calls. Some APIs return data in the response body and others will only return a HTTP status. For example, CloudCenter DELETE calls return a Status 204 No Content after deleting the resource in the background.

Synchronous

Synchronous APIs indicate that the program execution waits for a response to be returned by the API. The execution does not proceed until the call is completed. The real state of the API request is available in the response.

Asynchronous

Asynchronous APIs do not wait for the API call to complete. Program execution continues, and until the call completes, you can issue GET requests to review the state after the submission, during the execution, and after the call completion. Use the Get Operation Status API to retrieve the status of an asynchronous operation.

As asynchronous calls may take some time to complete, they return HTTP Status Codes responses containing information with a HTTP Status Code, which allows you to retrieve the progress, status, response, and other information for the call.

After submitting an asynchronous API call:

  1. Retrieve the resource URL from the HTTP Status Codes.
  2. Use this location URL and query the system using GET calls. While the call is in progress and you issue the GET request, you get additional details of the operation being performed. These details are only available while the operation is in various states of execution (RUNNING, SUCCESS, FAILED).
  3. When the asynchronous API call completes successfully, issue a GET request to view the SUCCESS state and the resource URL for this operation.

Call States

In the following example of a Create Cloud Account API:

  • The various states of execution (RUNNING, SUCCESS, FAILED) are highlighted in corresponding colors
  • The first and last GET requests are in bold to show the sequence of events

Operation ID Availability

Operation IDs (displayed below the Location URL in the above image) allow you to to query the status of asynchronous APIs and are only available for a brief period as identified in the following table:

Operation ID AvailabilityDescription
5 minutesThe Operation ID is available for five minutes if the operation completes (regardless of success or failure).
1 hourThe Operation ID is available for one hour if the operation times out and does not complete.

  • No labels
© 2017-2019 Cisco Systems, Inc. All rights reserved