Synchronous and Asynchronous APIs

 

CloudCenter 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 CloudCenter 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. 

As asynchronous calls may take some time to complete, they return HTTP Status Code responses containing information with a HTTP Location URL, 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 Location URL.
  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. For an example of an asynchronous call, see Create User with Activation is an asynchronous call.  See Resource URL and ID for additional context.

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
  • Example – Create User with Activation:

     Sample response for an asynchronous operation
    {
        "operationId": "888210d0-bde9-44d8-a9a5-a273d000c427",
        "status": "SUCCESS",
        "msg": "Finished",
        "progress": 100,
        "timestamp": 1464909251317,
        "additionalParameters": null,
        "operationHistory": [
            "",
            "",
            "Starting task: activateUserAccount",
            "Validating user and applying default cloud settings",
            "Validated user and applied default cloud settings successfully",
            "Finished task: activateUserAccount",
            "Starting task: activateCloudAccounts",
            "Activating user account on cloud 'Amazon US East (Virginia)'",
            "Activation of user account on cloud 'Amazon US East (Virginia)' completed successfully",
            "Finished task: activateCloudAccounts",
            "Starting task: initializeCredit",
            "Initializing Singup/Bundle credit for the user",
            "Applied Signup/Bundle credit successfully",
            "Finished task: initializeCredit",
            "Starting task: addDefaultPolicy",
            "Applied default policies successfully",
            "Finished task: addDefaultPolicy",
            "Starting task: importApps",
            "No apps found for import",
            "Finished task: importApps",
            "Finished"
        ],
        "subtaskResults": {
            "activateUserAccount": {
                "operationId": "38b0d915-44c8-49ff-a58c-06ae7a1f72f5",
                "status": "SUCCESS",
                "msg": "Finished task: activateUserAccount",
                "progress": 100,
                "timestamp": 1464909251130,
                "additionalParameters": null,
                "operationHistory": [
                    "Starting task: activateUserAccount",
                    "Validating user and applying default cloud settings",
                    "Validated user and applied default cloud settings successfully",
                    "Finished task: activateUserAccount"
                ],
                "subtaskResults": null,
                "resourceUrl": null
            },
            "activateCloudAccounts": {
                "operationId": "79d9d83a-8eb2-4764-9884-8afbcc669f5e",
                "status": "SUCCESS",
                "msg": "Finished task: activateCloudAccounts",
                "progress": 100,
                "timestamp": 1464909251229,
                "additionalParameters": null,
                "operationHistory": [
                    "Starting task: activateCloudAccounts",
                    "Activating user account on cloud 'Amazon US East (Virginia)'",
                    "Activation of user account on cloud 'Amazon US East (Virginia)' completed successfully",
                    "Finished task: activateCloudAccounts"
                ],
                "subtaskResults": null,
                "resourceUrl": null
            },
            "initializeCredit": {
                "operationId": "94d281d7-a85e-4784-855b-f8a52a45e535",
                "status": "SUCCESS",
                "msg": "Finished task: initializeCredit",
                "progress": 100,
                "timestamp": 1464909251255,
                "additionalParameters": null,
                "operationHistory": [
                    "Starting task: initializeCredit",
                    "Initializing Singup/Bundle credit for the user",
                    "Applied Signup/Bundle credit successfully",
                    "Finished task: initializeCredit"
                ],
                "subtaskResults": null,
                "resourceUrl": null
            },
            "addDefaultPolicy": {
                "operationId": "a5af132b-2554-4a36-95be-18bf77549622",
                "status": "SUCCESS",
                "msg": "Finished task: addDefaultPolicy",
                "progress": 100,
                "timestamp": 1464909251287,
                "additionalParameters": null,
                "operationHistory": [
                    "Starting task: addDefaultPolicy",
                    "Applied default policies successfully",
                    "Finished task: addDefaultPolicy"
                ],
                "subtaskResults": null,
                "resourceUrl": null
            },
            "importApps": {
                "operationId": "43dacfe5-0a4b-497f-b8eb-8a6702381711",
                "status": "SUCCESS",
                "msg": "Finished task: importApps",
                "progress": 100,
                "timestamp": 1464909251290,
                "additionalParameters": null,
                "operationHistory": [
                    "Starting task: importApps",
                    "No apps found for import",
                    "Finished task: importApps"
                ],
                "subtaskResults": null,
                "resourceUrl": null
            }
        },
        "resourceUrl": "/v1/users/5"
    } 

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.