×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

Unsupported content

 

This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.
BMC Cloud Lifecycle Management 3.1 ... Developing Getting started with the API

Synchronous and asynchronous operations

The BMC Cloud Lifecycle Management API supports both synchronous and asynchronous operating modes. In synchronous mode, you specify a timeout value and the system waits until the requested operation either finishes or times out to return an HTTP response. When the requested operation does not finish before the specified timeout, the HTTP response contains a Task object in the message body. Otherwise, the HTTP response contains a cloud object appropriate to the request. In asynchronous mode, the system immediately returns an HTTP response that contains a Task object in the message body.

Recommendation

Always code to the asynchronous API by setting the HTTP request timeout value to 0.

You select the operating mode by specifying a value for the timeout object in the HTTP request message body. If you do not specify a timeout value, it defaults to -1. The following table lists the integer timeout values that you can specify:

HTTP request timeout values

Value

Description

0

Asynchronous mode, which returns a response immediately. The message body of the response always contains a Task object.

-1

Synchronous mode, using the system default timeout value.

1..*

Synchronous mode, using the specified timeout value in seconds.

All GET methods are synchronous. Because some of them might return a large number of objects, the GET APIs enable you to filter the query to limit the number of objects returned. POST and DELETE methods are expected to take a long time.

To find out whether a task is finished, you can either poll the Task object for status or request a callback upon completion.

You can poll the Task object via a GET request on the task identifier by using the GET csm/task/guid pattern or by sending a GET request to the taskStatusURI object included in the response.

If an HTTP request contains a callback URL, a POST message is sent to the callback URL when the task is finished. The callback must be a POST because it is not idempotent. The API allows only the specification of the callback URL. If the client system is concerned about authentication, you must ensure that the callback URL embeds a unique token to authenticate the callback.

Polling examples

The following examples show an asynchronous static pool search request and the responses received by polling.

The following asynchronous HTTP request searches for static pools:


POST /csm/staticpool/search HTTP/1.1
Host: <apiServer>
Authentication-Token: <yourToken>

{"timeout" : 0}

The following Task response is returned:


HTTP/1.1 200 OK
Date: Thu, 07 Apr 2011 00:36:28 GMT
BMC-Transaction-ID: 0a444544-8cf0-4d95-bea7-ff226f51bc0c
Content-Type: application/json; charset=UTF-8
Content-Length: 350
Server: Jetty(6.1.x)

[
   {
      "cloudClass" : "com.bmc.cloud.model.beans.Task",
      "creationTime" : "2011/04/06 17:36:29 PDT",
      "guid" : "433cf70c-c1dc-4137-b8b4-cfa761f49988",
      "taskInternalUUID" : "46c723fa-48e0-41fd-86d5-47caa2318488",
      "taskState" : "QUEUED",
      "taskStatusURI" : 
         "http://172.22.174.37:8080/csm/task/46c723fa-48e0-41fd-86d5-47caa2318488/status"
   }
]

The following request for task status is made by issuing a GET request on the taskStatusURI returned in the previous response:


GET /csm/task/46c723fa-48e0-41fd-86d5-47caa2318488/status HTTP/1.1
Host: 172.22.174.37:8080
Authentication-Token: <yourToken>

The following response to the status request is returned:


HTTP/1.1 200 OK
Date: Thu, 07 Apr 2011 00:39:16 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 4120
Server: Jetty(6.1.x)

[
   {
      "cloudClass" : "com.bmc.cloud.model.beans.Task",
      "completionTime" : "2011/04/06 17:37:12 PDT",
      "creationTime" : "2011/04/06 17:36:29 PDT",
      "errors" : [],
      "guid" : "53c78509-e2f1-45d9-9028-c4c4e7af183c",
      "isCallout" : false,
      "isError" : false,
      "isSuccess" : true,
      "results" : [
         "com.bmc.cloud.model.beans.SearchResults:{\r\n  \"cloudClass\" : \"com.bmc.cloud.model.beans.SearchResults\",\r\n  \"guid\" : \"98bba6dc-be05-4b72-a0a5-dbf4d3b2791d\",\r\n  \"pageNo\" : 0,\r\n  \"pageSize\" : 0,\r\n  \"results\" : [ {\r\n    \"cloudClass\" : \"com.bmc.cloud.model.beans.StaticPool\",\r\n    \"actual\" : 17,\r\n    \"description\" : \"Default pool for pod CompactPODDev\",\r\n    \"externalID\" : \"52cfae96-730b-43ee-b530-cdcc99ebfd99:CompactPODDev_default_pool\",\r\n    \"forNetworkContainer\" : [ ],\r\n    \"guid\" : \"51354b3d-75cd-406e-bf53-051244e76125\",\r\n    \"inPod\" : \"/pod/5304ea7c-7992-4b00-9456-b4a45620f715\",\r\n    \"isDefault\" : true,\r\n    \"name\" : \"CompactPODDev_default_pool\",\r\n    \"owner\" : \"bhu_admin\",\r\n    \"pooledObjects\" : [ \"/virtualhost/f93b9c35-4272-4285-85a5-7a4c9a4806af\", \"/virtualresourcepool/181d3c0e-bdbc-45d5-b1cd-bfb2677d6925\", \"/virtualresourcepool/ea276992-0bb4-43b2-b63d-c0c9b69acba7\", \"/virtualresourcepool/45f40c04-f9a9-4543-ab43-cbb19d63c4d8\", \"/virtualresourcepool/2c6983c5-2f14-4e3f-aebb-461fc0d6b7d7\", \"/virtualresourcepool/b46ef274-1f8a-4bdd-8146-2ecbe3a9fb46\", \"/virtualresourcepool/dd5ed52b-e8c1-40d0-b212-b3fc6f58c545\", \"/virtualresourcepool/5029db5f-e38f-45a0-814b-747291c4ad30\", \"/virtualresourcepool/7e5788e3-b9f4-476b-ac7d-021e8f2435a9\", \"/virtualresourcepool/1ebc026b-7800-4b76-baa8-0d2971695ac3\", \"/virtualresourcepool/0b1fef73-74af-4cf2-9068-892f6601acd0\", \"/virtualresourcepool/a7a4f725-532f-4beb-ad5b-7fa1c8f62d10\", \"/virtualresourcepool/bb2c64e2-3357-4209-9c63-ed3cfdf867ee\", \"/virtualcluster/0e7d9f54-db4a-43a8-b139-159b2b186acf\", \"/virtualdatastore/6689dbf5-2e44-4fbd-ac34-91e796e6a500\", \"/virtualresourcepool/32a4e5ad-ad04-4935-9da0-62449055c3fb\", \"/virtualresourcepool/f826d0cc-7500-4ba0-86f0-e4b068c82362\" ],\r\n    \"reconciliationID\" : \"OI-be7ff062c7a9448eb14fafcf92ceef56\",\r\n    \"tokenID\" : \"CompactPODDev_default_pool\"\r\n  }, {\r\n    \"cloudClass\" : \"com.bmc.cloud.model.beans.StaticPool\",\r\n    \"actual\" : 1,\r\n    \"description\" : \"Compute Pool One.\",\r\n    \"forNetworkContainer\" : [ \"/networkcontainer/04e36fa8-9f8e-4415-a7c7-60b88b349e4d\" ],\r\n    \"guid\" : \"65cd213f-4a54-480f-bb4d-03b12b262924\",\r\n    \"inPod\" : \"/pod/5304ea7c-7992-4b00-9456-b4a45620f715\",\r\n    \"isDefault\" : false,\r\n    \"name\" : \" yComputePool\",\r\n    \"owner\" : \"bhu_admin\",\r\n    \"pooledObjectType\" : \"com.bmc.cloud.model.beans.VirtualCluster\",\r\n    \"pooledObjects\" : [ \"/virtualhost/2ddd18a0-bc2b-4cb0-a2dc-399e773c5257\" ],\r\n    \"reconciliationID\" : \"OI-4aed613fd707491aaa8a42ebd813ee07\",\r\n    \"tokenID\" : \" yComputePool\"\r\n  }, {\r\n    \"cloudClass\" : \"com.bmc.cloud.model.beans.StaticPool\",\r\n    \"actual\" : 2,\r\n    \"forNetworkContainer\" : [ ],\r\n    \"guid\" : \"8eb7a6fc-8c7b-460f-8680-f5d305005c5a\",\r\n    \"inPod\" : \"/pod/5304ea7c-7992-4b00-9456-b4a45620f715\",\r\n    \"isDefault\" : false,\r\n    \"name\" : \"VDS Pool\",\r\n    \"owner\" : \"bhu_admin\",\r\n    \"pooledObjectType\" : \"com.bmc.cloud.model.beans.VirtualDatastore\",\r\n    \"pooledObjects\" : [ \"/virtualdatastore/3342d1c1-a206-41f1-83cb-f5053cecebf2\", \"/virtualdatastore/6be93d4a-fb32-47d1-ac15-d9187d9fb4d4\" ],\r\n    \"reconciliationID\" : \"OI-88c3ed085c154309b1168e26d0868483\",\r\n    \"tokenID\" : \"VDS Pool\"\r\n  } ],\r\n  \"totalRows\" : 3\r\n}"
      ],
      "taskInternalUUID" : "46c723fa-48e0-41fd-86d5-47caa2318488",
      "taskProgress" : 100.0,
      "taskResultURI" : 
         "http://172.22.174.37:8080/csm/task/46c723fa-48e0-41fd-86d5-47caa2318488/result",
      "taskState" : "COMPLETED",
      "taskStatusURI" : 
         "http://172.22.174.37:8080/csm/task/46c723fa-48e0-41fd-86d5-47caa2318488/status",
      "taskSubState" : "task_success"
   }
]

The following is a request for the task results made by issuing a GET on the taskResultURI contained in the previous response:


GET http: /csm/task/46c723fa-48e0-41fd-86d5-47caa2318488/result HTTP/1.1
Host: 172.22.174.37:8080
Authentication-Token: <yourToken>

The following response to the previous request for the task results is returned:


HTTP/1.1 200 OK
Date: Thu, 07 Apr 2011 00:43:33 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 3121
Server: Jetty(6.1.x)

[
   {
      "cloudClass" : "com.bmc.cloud.model.beans.SearchResults",
      "guid" : "98bba6dc-be05-4b72-a0a5-dbf4d3b2791d",
      "pageNo" : 0,
      "pageSize" : 0,
      "results" : [
         {
            "actual" : 17,
            "cloudClass" : "com.bmc.cloud.model.beans.StaticPool",
            "description" : "Default pool for pod CompactPODDev",
            "externalID" : 
               "52cfae96-730b-43ee-b530-cdcc99ebfd99:CompactPODDev_default_pool",
            "forNetworkContainer" : [],
            "guid" : "51354b3d-75cd-406e-bf53-051244e76125",
            "inPod" : "/pod/5304ea7c-7992-4b00-9456-b4a45620f715",
            "isDefault" : true,
            "name" : "CompactPODDev_default_pool",
            "owner" : "bhu_admin",
            "pooledObjects" : [
               "/virtualhost/f93b9c35-4272-4285-85a5-7a4c9a4806af",
               "/virtualresourcepool/181d3c0e-bdbc-45d5-b1cd-bfb2677d6925",
               "/virtualresourcepool/ea276992-0bb4-43b2-b63d-c0c9b69acba7",
               "/virtualresourcepool/45f40c04-f9a9-4543-ab43-cbb19d63c4d8",
               "/virtualresourcepool/2c6983c5-2f14-4e3f-aebb-461fc0d6b7d7",
               "/virtualresourcepool/b46ef274-1f8a-4bdd-8146-2ecbe3a9fb46",
               "/virtualresourcepool/dd5ed52b-e8c1-40d0-b212-b3fc6f58c545",
               "/virtualresourcepool/5029db5f-e38f-45a0-814b-747291c4ad30",
               "/virtualresourcepool/7e5788e3-b9f4-476b-ac7d-021e8f2435a9",
               "/virtualresourcepool/1ebc026b-7800-4b76-baa8-0d2971695ac3",
               "/virtualresourcepool/0b1fef73-74af-4cf2-9068-892f6601acd0",
               "/virtualresourcepool/a7a4f725-532f-4beb-ad5b-7fa1c8f62d10",
               "/virtualresourcepool/bb2c64e2-3357-4209-9c63-ed3cfdf867ee",
               "/virtualcluster/0e7d9f54-db4a-43a8-b139-159b2b186acf",
               "/virtualdatastore/6689dbf5-2e44-4fbd-ac34-91e796e6a500",
               "/virtualresourcepool/32a4e5ad-ad04-4935-9da0-62449055c3fb",
               "/virtualresourcepool/f826d0cc-7500-4ba0-86f0-e4b068c82362"
            ],
            "reconciliationID" : "OI-be7ff062c7a9448eb14fafcf92ceef56",
            "tokenID" : "CompactPODDev_default_pool"
         },
         {
            "actual" : 1,
            "cloudClass" : "com.bmc.cloud.model.beans.StaticPool",
            "description" : "Compute Pool One.",
            "forNetworkContainer" : 
               [ "/networkcontainer/04e36fa8-9f8e-4415-a7c7-60b88b349e4d" ],
            "guid" : "65cd213f-4a54-480f-bb4d-03b12b262924",
            "inPod" : "/pod/5304ea7c-7992-4b00-9456-b4a45620f715",
            "isDefault" : false,
            "name" : " yComputePool",
            "owner" : "bhu_admin",
            "pooledObjectType" : "com.bmc.cloud.model.beans.VirtualCluster",
            "pooledObjects" : 
               [ "/virtualhost/2ddd18a0-bc2b-4cb0-a2dc-399e773c5257" ],
            "reconciliationID" : "OI-4aed613fd707491aaa8a42ebd813ee07",
            "tokenID" : " yComputePool"
         },
         {
            "actual" : 2,
            "cloudClass" : "com.bmc.cloud.model.beans.StaticPool",
            "forNetworkContainer" : [],
            "guid" : "8eb7a6fc-8c7b-460f-8680-f5d305005c5a",
            "inPod" : "/pod/5304ea7c-7992-4b00-9456-b4a45620f715",
            "isDefault" : false,
            "name" : "VDS Pool",
            "owner" : "bhu_admin",
            "pooledObjectType" : "com.bmc.cloud.model.beans.VirtualDatastore",
            "pooledObjects" : [
               "/virtualdatastore/3342d1c1-a206-41f1-83cb-f5053cecebf2",
               "/virtualdatastore/6be93d4a-fb32-47d1-ac15-d9187d9fb4d4"
            ],
            "reconciliationID" : "OI-88c3ed085c154309b1168e26d0868483",
            "tokenID" : "VDS Pool"
         }
      ],
      "totalRows" : 3
   }
]
Was this page helpful? Yes No Submitting... Thank you
Last modified by Amy Kurtzman on Feb 13, 2013
timeout

Comments

Log in or register to comment.

Passing input parameters with an API request
API concepts
© Copyright 2024 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.