Getting Started with the Cato API

This sample program is short and doesn't include any decision making logic or code to repeat actions.  It could have been kept even shorter by combining some of the lines of code into a single line.  The extra lines of code have been included to make it easier to explain what is going on.

# Import Python library code
import os
import urllib.request
import ssl
import json

# Obtain the Cato API Key from an environment variable
cato_api_key = os.getenv("CATO_API_KEY")

# Create the GraphQL request to be sent
get_total_admins = '''{
    admins (accountID: 12345) {
        total        
    }
}'''
graphql_query = {'query': get_total_admins}

# Build the http request
cato_api_url = "https://api.catonetworks.com/api/v1/graphql2"
headers = {'x-api-key': cato_api_key,
           'Content-Type':'application/json'}
unverified_ctx = ssl._create_unverified_context()
json_post = json.dumps(graphql_query)
json_post_encoded = json_post.encode()
request = urllib.request.Request(url=cato_api_url, data=json_post_encoded, headers=headers)

# Send the query and convert the response into a Python dictionary
response = urllib.request.urlopen(request, context=unverified_ctx, timeout=30)
json_response_encoded = response.read()
json_response = json_response_encoded.decode()
get_admins_total_result = json.loads(json_response)

# Extract the total from the returned data and print it out
total = get_admins_total_result['data']['admins']['total']
print('The total number of admins defined with your account is: {}'.format(total))

The diagram provided below shows the sequence of events that take place when the program is run:

One of the reasons for using Python for the example program is the availability of a rich set of libraries.  These libraries provide functions and objects that can handle a vast range of tasks.  We will now go through each imported library and provide notes to explain why it is needed.

import os

import urllib.request

import ssl

import json

This line of code uses the getenv library function to read the API key from an environment variable and assign it to a variable.

cato_api_key = os.getenv("CATO_API_KEY")

The Cato GraphQL server expects to receive this key in a nHTTP header.  The key is not provided in the JSON document because the GraphQL specification does not include authorisation as part of the standard.  Including authorisation in the JSON document would be a violation of the specification.  The Cato API key is generated via the Cato Management Application.  For more information about creating an API key, see Generating API Keys for the Cato API.

The next couple of lines of code create a Python directory containing one key/value pair.  The value of the entry is built using a Python multi-line string that defines the query that will be sent to the GraphQL server.

get_total_admins = '''{
    admins (accountID: 12345) {
        total    
    }
}'''
graphql_query = {'query': get_total_admins}

The Cato GraphQL server will interpret this string to mean: execute the function get_total_admins, passing two arguments to it (accountID and type) and returning only the "total" number of entities .  Or stated more directly, "Return the total number of entities of admins that are defined for example account # 12345".  This specific example of the admins API call  illustrates an important advantage of a GraphQL API

The fact is, the admins call can return a lot more data.  For example, it is possible for an application to request that admins return details about each admin.  However, this application only needs to know the total number of admins.  This characteristic of GraphQL avoids what is referred to as over-fetching and can greatly simplify the code needed to implement the application.

In this section of the program a request object is constructed.  This object will be used to send the API call to the GraphQL server using HTTPS. This request object requires information that is provided by several other objects that need to be created first.   First of all, a simple string object is constructed to contain the URL of the GraphQL server that the request object will send the query to.

cato_api_url = "https://api.catonetworks.com/api/v1/graphql2"

Next a dictionary is created that defines two HTTP headers.  These headers are used by the request object to construct a HTTP POST request that the GraphQL server will accept.  Without these headers the HTTP POST requests would be rejected by the server.

headers = {'x-api-key': cato_api_key,           
           'Content-Type':'application/json'}

The next line of code creates an SSL context object. Python uses this object to determine how it should encrypt HTTP requests and send them using Transport Level Security (TLS). Here we are creating an SSL context object that does not verify certificates. This has been done to avoid certificate errors in networks subject to upstream TLS inspection.

unverified_ctx = ssl._create_unverified_context()

The next two lines of code convert the Python dictionary containing the Cato API call into a string and encode that string into bytes.  The second step is required to allow the string to be transmitted over the network.

json_post = json.dumps(graphql_query)
json_post_encoded = json_post.encode()

Finally the request object is created and the program is now ready to send the get_total_admins call to the server.

request = urllib.request.Request(url=cato_api_url, data=json_post_encoded, headers=headers)

Here the program sends the request to the GraphQL server by calling the urlopen function of the urllib library.  Callling this function will result in the return of a  HTTPResponse object.  

response = urllib.request.urlopen(request, context=unverified_ctx, timeout=30)

The object returned by the urlopen function includes a body field which holds the JSON document returned by the server.  This can be extracted from the object by executing its read method which returns a bytes object.  This bytes object is then converted into a string object by calling the decode method of the bytes object.

json_response_encoded = response.read()
json_response = json_response_encoded.decode()

This decoded string contains a JSON document which will look like this:

{    
    "data" : {
         "admins" : {
              "total": 4
         }
    }
}

As you will see, the format of the returned data looks very like the format of the request that was sent to the server.  This is intentional and another advantage of using the GraphQL specification to implement an API.  This approach simplifies the coding of the application by keeping the returned data in the same shape as the request.

The final line of code in this section of the program uses the json library function 'loads' to convert the returned JSON string into a Python nested dictionary.  

get_total_admin_result = json.loads(json_response)

The last two lines of the code extract the value from the total field that was returned by the server and print it out to the console. 

total = get_total_admins_result['data']['get_total_admins']['total']
print('The total number of admins defined for your account is: {}'.format(total)) 

The output will look like this:

The total number of admins defined for your account is: 4