Using Python with the ReST API

Prerequisites

We suggest using the requests package to make ReST API calls with python, and the requests_toolbelt package to assist in calls using large file uploads like asset imports. Use pip to install prerequisites:

pip install requests
pip install requests_toolbelt

Use an ECA Certificate with python

Once requests is installed, you can leverage it to add your client ECA certificate to API requests to HmC. Note, certificates are not required in cons3rt.com. To convert your ECA certificate to a passwordless PEM file for use with python, run the following command on a machine with openssl:

openssl pkcs12 -in certfile.pfx -out certfile.pem -nodes

Then include the certificate path as the cert argument to any python requests call like this:

  • response = requests.get(url, headers=headers, verify=False, cert='/path/to/certfile.pem')

Setting Headers

For HmC requiring certificate-based authentication, set headers:

headers = {
    'token': '12345-67890-12345-67890',
    'Accept': 'application/json'
}

For cons3rt.com or any site that does not require certificate-based authentication, add the username header:

headers = {
    'username': cons3rt_username,
    'token': '12345-67890-12345-67890',
    'Accept': 'application/json'
}

Use the following optional headers depending on the requirements of the ReST API call, use Keep-Alive when importing or updating an asset:

headers['Connection'] = 'Keep-Alive'
headers['Content-Type'] = 'application/json'

Handling DoD Root CA Certificates for HmC

The HmC DoD root CA certificate is issues by the DoD, and is not included in most standard certificate bundles (and definitely not in the python distribution). There are two ways to handle this:

  • The easy but insecure way, set verify=False in the request like this:
    • response = requests.get(url, headers=headers, verify=False, cert='/path/to/certfile.pem')
  • Create a cert bundle PEM file containing the DoD root certs, and provide the path to the verify arg in the request like this:
    • response = requests.get(url, headers=headers, verify='/path/to/dod_bundle.pem', cert='/path/to/certfile.pem')

Make a ReST API Call with Python

See these examples on Github for sample Python code.

First determine the base URL for the CONS3RT site you are connecting to:

  • For HmC: base_url = 'https://www.milcloud.hanscom.hpc.mil'
  • For cons3rt.com: base_url = 'https://www.cons3rt.com'

Review the API documentation for the ReST API call and determine the:

  • HTTP method (GET, PUT, POST, DELETE, etc.)
  • URL for the call (e.g. /rest/api/drs/)

Let's put it all together! Now you have all the information you need to make a ReST API call with Python Requests. Here are some sample calls, note these sample calls are written for HmC with certificate-based authentication, so for cons3rt.com you can set verify=None and cert=None:

  • List your Deployment Runs
import requests
base_url = 'https://www.milcloud.hanscom.hpc.mil'
headers = {
    'token': '12345-67890-12345-67890',
    'Accept': 'application/json'
}
response = requests.get(base_url + '/rest/api/drs/?search_type=SEARCH_ALL&in_project=false', headers=headers, verify='/path/to/dod_bundle.pem', cert='/path/to/certfile.pem')
print('CONS3RT returned code: ' + str(response.status_code))
print('API call output: ' + response.content)
  • Import a Software Asset
import requests
from requests_toolbelt import MultipartEncoder
asset_file_name = 'asset.zip'
asset_zip = '/path/to/asset/zip/file/' + asset_file_name
base_url = 'https://www.milcloud.hanscom.hpc.mil'
headers = {
    'token': '12345-67890-12345-67890',
    'Accept': 'application/json'
}
headers['Connection'] = 'Keep-Alive'
    with open(asset_zip, 'r') as f:
        form = MultipartEncoder({
            "file": (asset_file_name, f, "application/octet-stream"),
            "filename": asset_file_name
        })
        headers["Content-Type"] = form.content_type
        response = requests.post(base_url + '/rest/api/software/import', headers=headers, data=form, verify=False, cert=cert_file)
        print('CONS3RT returned code: ' + str(response.status_code))
        print('API call output: ' + str(response.content))
  • Launch a Deployment!
import requests
base_url = 'https://www.milcloud.hanscom.hpc.mil'
deployment_id = '12345'
headers = {
    'token': '12345-67890-12345-67890',
    'Accept': 'application/json'
}
body = { ... set body fields according to the ReST API documentation ... }  
response = requests.put(base_url + '/rest/api/deployments/{i}/execute/'.format(i=deployment_id), headers=headers, data=body, verify='/path/to/dod_bundle.pem', cert='/path/to/certfile.pem')
print('CONS3RT returned code: ' + str(response.status_code))
print('API call output: ' + response.content)