¿Qué es la API de Cato

Este artículo le ayuda a comenzar con la API de Cato para monitorear y configurar la configuración y los elementos en su cuenta.

"Visión general"

La API de Cato es la interfaz de automatización principal para la integración sin problemas con el Cato Cloud. Utilice las API de Cato para establecer flujos de trabajo operativos eficientes como la implementación y configuración, así como una supervisión completa del estado, estadísticas, recolección de datos y análisis para optimizar la gestión de su red y seguridad.

Punto Final y Esquema de la API de Cato

La URL para el punto final y el esquema de la API es específica para la ubicación donde se aloja la instancia de la Aplicación de Gestión de Cato (CMA). Puede haber un valor <prefix> que se añade a la URL de su cuenta CMA y al punto final y esquema de la API.

La URL para el punto final de la API está en el formato, https://api.<prefix>.catonetworks.com/api/v1/graphql2.

La URL para el esquema de la API está en el formato, https://api.<prefix>.catonetworks.com/api/schema.

URLs para el Punto Final de la API

Si no hay un prefijo (cc.catonetworks.com), entonces use la siguiente URL: https://api.catonetworks.com/api/v1/graphql2
Si hay un prefijo (como cc.us1.catonetworks.com), entonces usaría la siguiente URL (modifique el prefijo para diferentes ubicaciones): https://api.us1.catonetworks.com/api/v1/graphql2

URLs para el Esquema de la API

Si no hay un prefijo (cc.catonetworks.com), entonces use la siguiente URL: https://api.catonetworks.com/api/schema
Si hay un prefijo (como cc.us1.catonetworks.com), entonces usaría la siguiente URL (modifique el prefijo para diferentes ubicaciones): https://api.us1.catonetworks.com/api/schema

Documentación del Esquema de la API

Las API de Cato están construidas sobre GraphQL, ofreciendo una interfaz intuitiva que es completamente compatible con herramientas y clientes de API RESTful. GraphQL también proporciona la flexibilidad adicional para interrogar exactamente los datos que necesita, reduciendo la sobrecarga de datos y mejorando la eficiencia.

La documentación de la API de Cato está disponible en Referencia de la API de GraphQL de Cato Networks, que contiene:

Definición y documentación del esquema
Ejemplos de llamadas a la API y respuestas de muestra correspondientes
Punto final de la API de GraphQL con un Playground interactivo para explorar y probar la API

Ciclo de Vida de la API

Esta sección describe las diferentes etapas del ciclo de vida según el nivel de madurez y la disponibilidad de una API específica.

Cada nueva API se lanza inicialmente en la etapa Beta. La transición de Beta a GA está sujeta a revisión interna y consideración para verificar que la API es estable y lista para producción. Típicamente, la transición de Beta a GA toma aproximadamente un año.

Nota:
Nota: El ciclo de vida descrito a continuación se refiere solo a la API formal de Cato como se define en la Referencia de la API de GraphQL de Cato Networks. No cubre herramientas adicionales ni ejemplos que puedan proporcionarse como referencias.
Por ejemplo, no cubre los ejemplos de código abierto y utilidades disponibles en la cuenta de GitHub de Cato. Estos recursos se proporcionan "tal cual" sin garantía ni obligación de desarrollo continuo, mantenimiento o soporte.

Niveles de Madurez de la API

Estos son los niveles de madurez de la API como parte de la etapa del ciclo de vida:

Beta: Las API en la etapa Beta son completas en cuanto a funcionalidades y se consideran completamente operativas, haciéndolas adecuadas para su uso en entornos de producción. Sin embargo, pueden sufrir cambios basados en la retroalimentación de los usuarios o consideraciones adicionales. Estos cambios, incluidos los cambios importantes en el esquema de la API, pueden ocurrir con poca antelación y requerir actualizaciones en el código del cliente.
GA (Disponibilidad General): Las API en GA son estables, listas para producción y vienen con soporte a largo plazo y compromisos para la compatibilidad hacia atrás. Los cambios importantes en el esquema de la API son raros y se anuncian con suficiente antelación para proporcionar tiempo suficiente para ajustes en el código del cliente.
Las API que no están explícitamente etiquetadas como Beta se consideran GA. En algunos casos, dentro de una API en GA, los campos, tipos e inputs individuales pueden estar marcados como Betas.

Niveles de Disponibilidad de la API

Estos son los niveles de disponibilidad para las API como parte de la etapa del ciclo de vida:

EA (Disponibilidad Temprana): Las API en EA están disponibles para un grupo limitado de usuarios para pruebas y retroalimentación antes de un lanzamiento más amplio. El acceso puede requerir aprobación especial o condiciones.
Despliegue Gradual: Siguiendo las mejores prácticas de la industria para servicios en la nube, las API de Cato se despliegan gradualmente para garantizar estabilidad y monitorear el rendimiento, con disponibilidad expandiéndose a todas las cuentas con el tiempo.
Las API que no están marcadas como EA o Despliegue Gradual se consideran totalmente desplegadas y accesibles para todos los usuarios.

Resumen de Etiquetas de la API

Esta sección resume las etiquetas utilizadas para las API en la documentación según los niveles de madurez y disponibilidad.

Las API sin etiqueta están totalmente disponibles para todas las cuentas y raramente hay cambios importantes en el esquema. Cualquier cambio de este tipo se anunciará con varios meses de antelación. Para más información sobre estos cambios, vea abajo Cambios Potencialmente Importantes en el Esquema.

EA
- Solo disponible para clientes que se unan al programa EA de Cato, para unirse, por favor contáctenos en ea@catonetworks.com
Beta
- Puede haber cambios en el esquema
- Aviso limitado para cambios importantes, posiblemente tan corto como dos semanas
- Las API Beta soportan funcionalidad completa
Despliegue
- Estas API en GA se están desplegando gradualmente a todas las cuentas durante un período de algunas semanas
- Hacer llamadas a una API en estado de Despliegue puede resultar en un mensaje de error porque esa API aún no está disponible para su cuenta

Cambios Potencialmente Importantes en el Esquema

Esta sección discute cuándo Cato realiza cambios en el esquema de la API de GraphQL que pueden impactar el comportamiento y los resultados de las llamadas a la API.

¿Qué es un Cambio Potencialmente Importante en GraphQL?

Un cambio potencialmente importante en GraphQL ocurre cuando las modificaciones a la API requieren que las aplicaciones cliente actualicen sus consultas o lógica para mantener la funcionalidad. Ejemplos incluyen:

Eliminar un campo, tipo o argumento.
Renombrar campos, tipos o argumentos.
Modificar los valores predeterminados para argumentos de una manera que cambia los resultados esperados de consultas o mutaciones.
Alterar el tipo o comportamiento de un campo de una manera que impacta la compatibilidad. Por ejemplo, cambiar el tipo de un campo (por ejemplo, de Int a String) o modificar la anulabilidad de un argumento (por ejemplo, de anulable a no anulable).

Anunciar y Gestionar Cambios Potencialmente Importantes

Trabajamos lo más arduamente posible para evitar cambios potencialmente importantes. Sin embargo, en el raro caso de que haya tal cambio, se comunicará a los clientes como se explica a continuación en Notificación de APIs Fin de Vida.

Estos cambios pueden ocurrir más frecuentemente para las API Beta pero son raros para las API en GA.

APIs Obsoletas

Una API o un campo marcado como Obsoleto indica que su uso ya no es recomendado y que existe una mejor alternativa. Recomendamos que actualice scripts y procesos para no usar APIs y campos obsoletos para mantener el comportamiento y funcionalidad esperada.

Notificación de APIs Fin de Vida

Si una API o un campo está planificado para su eliminación o reemplazo, pasará por un proceso de Fin de Vida (EoL). Este proceso incluye los siguientes pasos:

Marcar la API o Campo como Obsoleto
1. La API o campo planificado para eliminación se marca como Obsoleto en la Referencia de la API de GraphQL de Cato Networks.
2. Esta etiqueta se acompaña de un mensaje que especifica una API o campo alternativo, si corresponde, y la fecha planificada para el Fin de Vida.
Notificaciones de Fin de Vida
1. El artículo Cambios Potencialmente Importantes y Fin de Vida de la API de Cato se actualiza con la fecha específica en que el esquema se actualizará con el cambio.
2. El período de tiempo entre la notificación y los cambios en el esquema es el siguiente:
  - API en GA: Al menos 3 meses de antelación y generalmente 6 meses de antelación
  - API Beta: Típicamente 2 semanas de antelación
3. Durante el período de tiempo entre la notificación de Fin de Vida y la fecha de Fin de Vida, se espera que los clientes actualicen el código del cliente para adaptarse a los cambios en el esquema de GraphQL.

Cambios de Esquema No Importantes

Los cambios en GraphQL que no sean importantes pero aún significativos, como nuevas APIs o nuevos campos, se anuncian en el artículo Registro de Cambios de la API de Cato.

La Referencia de la API de GraphQL de Cato Networks siempre incluye el esquema completo soportado y actualizado de GraphQL.