Introducción
Cada instancia de ZofToken tiene dos canales de comunicación:
- Un protocolo binario de bajo tráfico y alta performance, diseñado a medida, para que las aplicaciones (ya sea ZofToken Universal App o cualquier otra que implemente ZofToken SDK) realicen
las operaciones vinculadas a los tokens.
- Una API estándar, basada en REST, para integrar cualquier tipo de sistema existente con la solución.
Si bien el protocolo binario no es secreto y de hecho está disponible como parte del ZofToken SDK para que otras aplicaciones o componentes puedan operar directamente como tokens, este documento
busca describir la segunda API mencionada previamente dado que es la que cualquier organización necesita para integrar sus sistemas o servicios con una instalación privada de ZofToken Server o ZaaS.
Diseño de la API
En la introducción, la API se describe como "basada en REST" en lugar de simplemente REST dado que se han tomado una serie de decisiones específicas de diseño para maximizar la simpleza de
integración. Desde el inicio, buscamos que la operación más básica requerida para que un sistema se integre a ZofToken (obtener el estado de un token) pueda realizarse con un único HTTP GET
que fuera igual simple de ejecutar en el sistema más moderno o en un sistema que estuviera operativo hace 15 años.
Tomando lo anterior en cuenta, la siguiente es una lista de dichas decisiones de diseño:
- Los únicos dos verbos utilizados en la API son GET y POST que deberían ser soportados de inmediato por cualquier librería, SDK o lenguaje de programación que pueda realizar conexiones
HTTP. Este es el motivo, por ejemplo, por el cual borrar un token se realiza con un POST a una llamada específica en lugar de utilizar un DELETE a la misma llamada donde se había
solicitado el enrolamiento.
- Cada GET solamente utilizan parámetros de tipo "query", mientras que cada POST utiliza un "body" en formato JSON. Esta forma de gestionar parámetros es estándar en cualquier sistema
moderno pero puede ser construida o procesada facilmente en sistemas antiguos.
- Cada llamado incluye un authkey para validar un nivel apropiado de autorización. Si bien muchas APIs modernas utilizan OAuth 2.0 para autorización de transacciones, este modelo agrega
otra capa de complejidad, potencialmente significativa, para la integración con sistemas antiguos, mientras que ZofToken gestiona estas autorizaciones de forma más simple a través
de authkeys definidas por el usuario.
- Si bien cada respuesta incluye un mensaje legible para ayudar en la integración y detección de problemas, se utilizan códigos HTTP estándares para dichas respuestas: 200 es una llamada
que fue ejecutada correctamente, 400 es una llamada incorrecta (tipicamente por un error en los parámetros), 403 es un problema de seguridad (típicamente por un authkey inválido), 404
implica que no se pudo encontrar un objeto (típicamente un usuario o servicio inválidos) y 500 representa un error interno (típicamente un problema transitorio en una base de datos
que puede reintentarse y que en cualquier caso se guarda en una bitácora para detectar y corregir potenciales problemas).
- Este es un aspecto más vinculado a la configuración del servidor que a la API pero dado que afecta la forma en la que se hacen las llamadas se menciona en este punto. El servidor de
ZofToken puede ser configurado para aceptar llamadas HTTPS (lo cual naturalmente requiere proveer al servidor de un certificado digital junto con la clave privada asociada) o para aceptar
llamadas HTTP sin encripción (usualmente en casos donde el servidor se encuentre detrás de un proxy reverso seguro). Independientemente de la decisión de configuración que se haya
implementado, se recomienda nunca realizar llamadas en un canal sin encripción aun en redes internas.
Descripción de la API
A continuación se presenta la API en múltiples formatos diferentes, así cada desarrollador que esté trabajando en una integración puede seleccionar aquella que mejor resulte para su modelo de desarrollo
y las herramientas que se estén utilizando.
Para instalaciones privadas de ZofToken Server, de todos modos se recomienda obtener una subscripción gratuita de ZaaS, dado que de este modo se cuenta con una plataforma instantánea para la realización
de experimentos y pruebas de integración.
Los formatos disponibles para la API son:
OpenAPI 3.0
Este es el archivo con la descripción básica según el estándar OpenAPI 3.0 disponible en formatos YAML y JSON.
Referencia en PDF
Este es el mismo archivo OpenAPI convertido a una referencia legible, utilizando el conversor provisto por RapiPDF.
Insomnia
Este es un ambiente de trabajo exportado para la popular herramienta "Insomnia REST Client" que incluye todos los llamados de la API.
Ejemplo básico de uso
El siguiente procedimiento sencillo, que no debería llevar más de 10 minutos, facilita el entendimiento de como opera la solución ZofToken.
- Instalar ZofToken Universal App para la plataforma correspondiente.
- Instalar el cliente de Insomnia.
- Registrarse para una subscripción de ZaaS gratuita (a efectos de este ejemplo, la subscripción se llama ("apitest”).
- En la interface de ZaaS, crear un servicio dentro de la subscripción (a efectos de este ejemplo, el servicio se llama “testservice”).
- En la interface de Zaas, crear un usuario dentro de ese servicio (a efectos de este ejemplo, el usuario se llama “testuser”).
- Enrolar el usuario dentro de la aplicación ZofToken del smartphone.
- Importar el ambiente de trabajo correspondiente a la API dentro de Insomnia.
- Acceder a la opción "environment" y seleccionar “ZofToken”.
- Acceder a “Manage Environments”, configurar service_id (en este ejemplo, sería "apitest_testservice") y configurar auth_string (copiar el “Auth administrativo” provisto por ZaaS).
- A esta altura, ya se encuentra toda la configuración realizada para utilizar toda la API de ZofToken desde Insomnia. Se puede probar accediendo al llamado “Token Status” (cambiando
la identificación del usuario por el nombre configurado previamente (en este ejemplo “testuser”) que debería mostrar un 2 indicando que el token está cerrado si el proceso de enrolamiento
fue completado adecuadamente y luego un 1 cuando el token se encuentre abierto.
