Creating a SecureCloud API Request

The following task shows how to create an example API request. For this example, the EncryptVM() API will be used. The steps involved with creating each API request depend upon which API you are calling.

Note

Each of these programming tasks assumes that you are you are using a new programming code file. The examples shown are using Python programming language. Other programming languages, such as C++ or Java, are capable of performing the same requests.

Procedure

Define the required API variables.
EncryptVM() requires the GUIDs of the device and the virtual machine.
```
vm_guid = "639F2224-637D-49AA-876B-AFBAD59AFADA"
device_guid = "6068C4CA-A5A0-45AF-9266-6A2E9BC929EB"
```
Copy your digest authentication process and paste it into this part of the API request.

The digest authentication process parts can be placed at varying locations in the request code, as long as the programming language does not encounter sequencing problems. Declare the API URL variable before calling API URL requests.

See Creating a Digest Authentication Process.
Call your user access token request function.
```
user_token = get_user_token()
```
Create the API URL variable using the URL of the intended API.
EncryptVM() requires the GUID of the virtual machine.
```
api_url = "https://securecloudservice/broker/API.svc/v3.5/VM/%s/encrypt" % (vm_guid)
```
Create the body of the API request in XML format using any required variables.
EncryptVM() requires the variables for the GUIDs of the device and the virtual machine.
```
post_data = """<?xml version="1.0" encoding="utf-8"?>
      <vm imageGUID="%s"><devices><device msUID="%s"/></devices>
      </vm>""" % (vm_guid, device_guid)
```

Add the user access token and XML request body to the API request found in your digest authentication process.

Important

This adds two lines of text to the existing code of the digest authentication process. Do not create duplicate code. If your intended API does not require an XML request body, still add the user access token.

If necessary, move the API request section of the digest authentication process to after your variable declaration for the XML user access token request body.

See Creating a Digest Authentication Process.

req = urllib2.Request(api_url)
req.add_data(post_data)
req.add_header('Content-Type', 'application/xml; charset=utf-8')
req.add_header('BrokerName', digest_broker_account)
req.add_header('X-UserSession', user_token)

Create the API request.

try:
      sc_get_req = opener.open(req)
      res = sc_get_req.read()

Note

For the sake of this example, this section is just the beginning of the Python compound statement try. If using Python, continue this try statement until the end of the function.

Format the result into XML.

xmldata = xml.dom.minidom.parseString(res)

Perform error checking.

except urllib2.HTTPError, e:
      logging.error(e)
except urllib2.URLError, e:
      logging.error(e)
except Exception, e:
      logging.error(e)

Sample Code


# Create variables for each part of the broker account
# information.
digest_broker_account = "test_digest_account"
digest_password = "QTpYVL0QKI"
digest_realm = "securecloud@trend.com"

# Define the required API variables.
vm_guid = "639F2224-637D-49AA-876B-AFBAD59AFADA" # Example VM GUID
device_guid = "6068C4CA-A5A0-45AF-9266-6A2E9BC929EB" # Example device GUID

# Call your user access token request function.
user_token = get_user_token()

# Create the API URL variable using the URL of the intended API.
api_url = "https://securecloudservice/broker/API.svc/v3.5/VM/%s/encrypt" % (vm_guid)

# Create the body of the API request in XML format using any required variables.
post_data = """<?xml version="1.0" encoding="utf-8"?><vm imageGUID="%s"><devices><device msUID="%s"/></devices></vm>""" % (vm_guid, device_guid)

# Add broker account information and the API URL to the password manager in the same function.                      
pwd_mgr = urllib2.HTTPPasswordMgr()                       
pwd_mgr.add_password(digest_realm, api_url, digest_broker_account, digest_password)
      
# Add the broker account information and the API URL to the API request handler.                       
opener = urllib2.build_opener()
opener.add_handler(urllib2.HTTPDigestAuthHandler(pwd_mgr))

# Request the API using the API URL.
req = urllib2.Request(api_url)
req.add_data(post_data) # Add the XML request body
req.add_header('Content-Type', 'application/xml; charset=utf-8') # Set the request data type to XML format
req.add_header('BrokerName', digest_broker_account) # Include the broker account information in the header
req.add_header('X-UserSession', user_token) # Add the user access token

# Create the API request.
try:                                               
      sc_get_req = opener.open(req)                                              
      res = sc_get_req.read()

      # Format the result into XML.
      xmldata = xml.dom.minidom.parseString(res)

# Perform error checking.
except urllib2.HTTPError, e:
      logging.error(e)
except urllib2.URLError, e:
      logging.error(e)
except Exception, e:
      logging.error(e)

$('#title').html($('meta[name=description]').attr('content'));