Explicando un script de Python para la API de Cato

Este programa de ejemplo es corto y no incluye ninguna lógica de toma de decisiones ni código para repetir acciones.  Podría haber sido aún más corto combinando algunas de las líneas de código en una sola línea.  Se han incluido líneas de código adicionales para facilitar la explicación de lo que está sucediendo.

# Importar código de biblioteca de Python
import os
import urllib.request
import ssl
import json

# Obtener la clave de API de Cato de una variable de entorno
cato_api_key = os.getenv("CATO_API_KEY")

# Crear la solicitud de GraphQL para ser enviada
get_total_admins = '''{
    admins (accountID: 12345) {
        total        
    }
}'''
graphql_query = {'query': get_total_admins}

# Construir la solicitud http
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)

# Enviar la consulta y convertir la respuesta en un diccionario de Python
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)

# Extraer el total de los datos devueltos e imprimirlo
total = get_admins_total_result['data']['admins']['total']
print('El número total de administradores definidos con su cuenta es: {}'.format(total))

El diagrama proporcionado a continuación muestra la secuencia de eventos que tienen lugar cuando se ejecuta el programa:

Una de las razones para usar Python para el programa de ejemplo es la disponibilidad de un conjunto variado de bibliotecas.  Estas bibliotecas proporcionan funciones y objetos que pueden manejar una amplia gama de tareas.  Ahora examinaremos cada biblioteca importada y proporcionaremos notas para explicar por qué es necesaria.

import os

import urllib.request

import ssl

import json

Esta línea de código utiliza la función de biblioteca getenv para leer la clave de API de una variable de entorno y asignarla a una variable.

cato_api_key = os.getenv("CATO_API_KEY")

El servidor de GraphQL de Cato espera recibir esta clave en un encabezado HTTP.  La clave no se proporciona en el documento JSON porque la especificación de GraphQL no incluye la autorización como parte del estándar.  Incluir la autorización en el documento JSON sería una violación de la especificación.  La clave de API de Cato se genera a través de la Aplicación de Gestión de Cato.  Para obtener más información sobre cómo crear una clave de API, consulte Generación de claves de API para la API de Cato.

Las siguientes líneas de código crean un directorio de Python que contiene un par clave/valor.  El valor de la entrada se construye usando una cadena multilínea de Python que define la consulta que se enviará al servidor de GraphQL.

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

El servidor de GraphQL de Cato interpretará esta cadena para significar: ejecutar la función get_total_admins, pasándole dos argumentos (accountID y tipo) y devolviendo solo el "total" de entidades.  O dicho más directamente, "Devuelve el número total de entidades de administradores que están definidas para el ejemplo de cuenta # 12345".  Este ejemplo específico de la llamada de API admins ilustra una ventaja importante de una API de GraphQL

De hecho, la llamada admins puede devolver muchos más datos.  Por ejemplo, es posible que una aplicación solicite que admins devuelva detalles sobre cada administrador.  Sin embargo, esta aplicación solo necesita saber el número total de administradores.  Esta característica de GraphQL evita lo que se conoce como sobreobtener y puede simplificar enormemente el código necesario para implementar la aplicación.

En esta sección del programa se construye un objeto de solicitud.  Este objeto se utilizará para enviar la llamada de API al servidor de GraphQL utilizando HTTPS. Este objeto de solicitud requiere información que es proporcionada por varios otros objetos que necesitan ser creados primero.   Primero, se construye un objeto de cadena simple para contener la URL del servidor de GraphQL al que el objeto de solicitud enviará la consulta.

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

A continuación, se crea un diccionario que define dos encabezados HTTP.  Estos encabezados son utilizados por el objeto de solicitud para construir una solicitud HTTP POST que el servidor de GraphQL aceptará.  Sin estos encabezados, las solicitudes HTTP POST serían rechazadas por el servidor.

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

La siguiente línea de código crea un objeto de contexto SSL. Python usa este objeto para determinar cómo debería cifrar las solicitudes HTTP y enviarlas usando Seguridad a Nivel de Transporte (TLS). Aquí estamos creando un objeto de contexto SSL que no verifica certificados. Esto se ha hecho para evitar errores de certificado en redes sujetas a inspección TLS ascendente.

unverified_ctx = ssl._create_unverified_context()

Las siguientes dos líneas de código convierten el diccionario de Python que contiene la llamada de API de Cato en una cadena y codifican esa cadena en bytes.  El segundo paso es necesario para permitir que la cadena se transmita sobre la red.

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

Finalmente se crea el objeto de solicitud y el programa ahora está listo para enviar la llamada get_total_admins al servidor.

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

Aquí el programa envía la solicitud al servidor de GraphQL llamando a la función urlopen de la biblioteca urllib.  Llamar a esta función resultará en el retorno de un objeto HTTPResponse.  

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

El objeto devuelto por la función urlopen incluye un campo de cuerpo que contiene el documento JSON devuelto por el servidor.  Esto se puede extraer del objeto ejecutando su método read que devuelve un objeto de bytes.  Este objeto de bytes se convierte luego en un objeto de cadena llamando al método decode del objeto de bytes.

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

Esta cadena decodificada contiene un documento JSON que se verá así:

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

Como verás, el formato de los datos devueltos se parece mucho al formato de la solicitud que fue enviada al servidor.  Esto es intencional y otra ventaja de usar la especificación GraphQL para implementar una API.  Este enfoque simplifica la codificación de la aplicación al mantener los datos devueltos con la misma estructura que la solicitud.

La línea final de código en esta sección del programa utiliza la función 'loads' de la librería json para convertir la cadena JSON devuelta en un diccionario anidado de Python.  

get_total_admin_result = json.loads(json_response)

Las últimas dos líneas del código extraen el valor del campo total que fue devuelto por el servidor y lo imprimen en la consola. 

total = get_total_admins_result['data']['get_total_admins']['total']
print('El número total de administradores definidos para su cuenta es: {}'.format(total)) 

La salida se verá así:

El número total de administradores definidos para su cuenta es: 4