Callbacks

Cloud Infrastructure Automation REST API provides a callback functionality that allows you to receive responses from Cloud Infrastructure Automation server asynchronously. Callbacks can be used when you initiate a time consuming operation on an Cloud Infrastructure Automation resource, such as starting a server, creating a server, and so on. When using a callback, the Cloud Infrastructure Automation server will notify the caller when the operation is completed on the server side and will return information on the success or failure of the operation, which can then be processed as needed.

To use a callback, you will need to set up an HTTP server that will be listening for HTTP requests from the Cloud Infrastructure Automation server. The URL at which your server is listening for requests must then be included in the header of an HTTPS request that you are sending to the Cloud Infrastructure Automation server using the following format: x-callback-url: <URL>. For example:

x-callback-url: http://192.168.3.77:8081/bd6fsdb4-24sd-4a64

Once the operation is completed on the server side, the Cloud Infrastructure Automation server will send back an HTTP GET response to the URL that you provided in the original request. The response header will contain the following information:

Name	Value
x-paci-rc	0 (zero) if the operation was successfully completed (for example, a server has been started). Any other value indicates that the operation has failed. In such a case, X-Error-Code and X-Error-Message (see below) will be included in the response and contain the error code and the error message respectively.
x-error-code	If the operation failed, this contains the error code.
x-error-message	If the operation failed, this contains the error message.

When your HTTP server receives the response, it should send back a response to the Cloud Infrastructure Automation server as quickly as possible (without doing any additional processing). The response should contain the HTTP return code 200, which will tell the Cloud Infrastructure Automation server that you received the response. Until this happens, the Cloud Infrastructure Automation server will continue sending responses to your HTTP server at predefined intervals.

Examples

The following is a sample server creation request that provides a URL for the callback in its header (x-callback-url):

POST https://c2u-web:4465/paci/v1.0/ve

accept-encoding: identity
content-length: 913
content-type: application/xml
x-callback-url: http://192.168.3.77:8081/bd6fsdb4-24sd-4a64
authorization: <hidden>
<?xml version="1.0" ?>
  <ve>
    <name>test-lin-01</name>
    <description>Test_ve</description>
    <subscription-id>1</subscription-id>
    <cpu number="2" power="160"/>
    <ram-size>512</ram-size>
    <bandwidth>10</bandwidth>
    <no-of-public-ip>2</no-of-public-ip>
    <no-of-public-ipv6>2</no-of-public-ipv6>
    <ve-disk size="5"/>
    <platform>
      <template-info name="centos-6-x86_64"/>
    </platform>
  </ve>

You will receive an immediate response from the Cloud Infrastructure Automation server as usual, but once the server is created, your HTTP server will receive an HTTP GET response with a header similar to the following:

Host: 10.30.3.77:8081
x-paci-rc: 0 
Connection: keep-alive
Accept: */*
User-Agent: NING/1.0

In the example above, the x-paci-rc value is 0, which indicates that the server has been created successfully.