Cet article vous aide à démarrer avec l'API Cato pour surveiller et configurer les paramètres et les éléments de votre compte.
L'API Cato est l'interface d'automatisation principale pour une intégration transparente avec le Cato Cloud. Utilisez les API Cato pour mettre en place des flux de travail opérationnels efficaces tels que le déploiement et la configuration, ainsi que pour une surveillance complète de l'état, la collecte de statistiques et de données, et l'analyse pour rationaliser la gestion de votre réseau et de votre sécurité.
L'URL pour le point de terminaison de l'API et le schéma est spécifique à l'emplacement où l'instance de l'Application de gestion Cato est hébergée. Il peut y avoir une valeur de <prefix> qui est ajoutée à l'URL de votre compte CMA et au point de terminaison et au schéma de l'API.
L'URL pour le point de terminaison de l'API est au format, https://api.<prefix>.catonetworks.com/api/v1/graphql2.
L'URL pour le schéma de l'API est au format, https://api.<prefix>.catonetworks.com/api/schema.
URL pour le point de terminaison de l'API
-
S'il n'y a pas de préfixe (
cc.catonetworks.com), utilisez l'URL suivante :https://api.catonetworks.com/api/v1/graphql2 -
S'il y a un préfixe (tel que
cc.us1.catonetworks.com), vous utiliseriez l'URL suivante (modifiez le préfixe pour différents emplacements) :https://api.us1.catonetworks.com/api/v1/graphql2
URL pour le schéma de l'API
-
S'il n'y a pas de préfixe (
cc.catonetworks.com), utilisez l'URL suivante :https://api.catonetworks.com/api/schema -
S'il y a un préfixe (tel que
cc.us1.catonetworks.com), vous utiliseriez l'URL suivante (modifiez le préfixe pour différents emplacements) :https://api.us1.catonetworks.com/api/schema
Les API Cato sont construites sur GraphQL, offrant une interface intuitive entièrement compatible avec les outils et clients API RESTful. GraphQL offre également la flexibilité supplémentaire de demander exactement les données dont vous avez besoin, réduisant ainsi la surcharge de données et améliorant l'efficacité.
La documentation de l'API Cato est disponible à Cato Networks GraphQL API Reference, qui contient :
-
Définition et documentation du schéma
-
Exemples d'appels API et réponses échantillons correspondantes
-
Point de terminaison API GraphQL avec un Playground interactif pour explorer et tester l'API
Cette section décrit les différentes étapes du cycle de vie basées sur le niveau de maturité et la disponibilité d'une API spécifique.
Chaque nouvelle API est initialement publiée en phase Beta. La transition de Beta à GA est soumise à un examen et une considération internes pour vérifier que l'API est stable et prête pour la production. En général, la transition de Beta à GA prend environ un an.
Note
Note : Le cycle de vie décrit ci-dessous se réfère uniquement à l'API formelle Cato telle que définie dans la Référence GraphQL de Cato Networks. Il ne couvre pas les outils et exemples supplémentaires qui peuvent être fournis à titre de référence.
Par exemple, il ne couvre pas les exemples et utilitaires open-source disponibles sur le compte GitHub de Cato. Ces ressources sont fournies « en l'état » sans garantie ou obligation de développement, maintenance ou support ultérieur.
Voici les niveaux de maturité de l'API dans le cadre de l'étape du cycle de vie :
-
Beta : Les API en phase Beta sont complètes en termes de fonctionnalités et considérées comme entièrement opérationnelles, ce qui les rend adaptées à une utilisation dans des environnements de production. Cependant, elles peuvent subir des modifications basées sur les retours des utilisateurs ou des considérations supplémentaires. Ces modifications, y compris les changements rétro-incompatibles du schéma de l'API, peuvent survenir avec un court préavis et nécessitent des mises à jour du code client.
-
GA (Disponibilité Générale) : Les API en GA sont stables, prêtes pour la production, et bénéficient d'un support à long terme avec des engagements de compatibilité ascendante. Les changements rétro-incompatibles du schéma de l'API sont rares et sont annoncés bien à l'avance pour fournir suffisamment de temps pour les ajustements du code client.
Les API qui ne sont pas explicitement étiquetées comme Beta sont considérées comme GA. Dans certains cas, au sein d'une API GA, des champs, types et entrées individuels peuvent être marqués comme Betas.
Voici les niveaux de disponibilité pour les API dans le cadre de l'étape du cycle de vie :
-
EA (Disponibilité Anticipée) : Les API en EA sont disponibles pour un groupe limité d'utilisateurs pour les tests et retours avant un déploiement plus large. L'accès peut nécessiter une approbation ou des conditions spéciales.
-
Déploiement Progressif : Suivant les meilleures pratiques standard de l'industrie pour les services basés sur le cloud, les API Cato sont déployées progressivement pour garantir la stabilité et surveiller les performances, avec une disponibilité étendue à tous les comptes au fil du temps.
Les API non marquées comme EA ou Déploiement Progressif sont considérées comme entièrement déployées et accessibles à tous les utilisateurs.
Cette section résume les labels utilisés pour les API dans la documentation en fonction des niveaux de maturité et de disponibilité.
Les API sans label sont entièrement disponibles pour tous les comptes et les changements de schéma rétro-incompatibles sont rares. Tout changement de ce type sera annoncé plusieurs mois à l'avance. Pour en savoir plus sur ces changements, voir ci-dessous Changements de Schéma Potentiellement Rétro-incompatibles.
-
EA
-
Uniquement disponible pour les clients qui rejoignent le programme EA de Cato, pour rejoindre, veuillez nous contacter à ea@catonetworks.com
-
-
Beta
-
Il peut y avoir des changements dans le schéma
-
Avis limité pour les changements rétro-incompatibles, pouvant être aussi court que deux semaines
-
Les API Beta prennent en charge toutes les fonctionnalités
-
-
Déploiement
-
Ces API GA sont progressivement déployées sur tous les comptes sur une période de quelques semaines
-
L'appel d'une API en statut Déploiement peut entraîner un message d'erreur car cette API n'est pas encore disponible pour votre compte
-
Cette section discute des moments où Cato apporte des modifications au schéma de l'API GraphQL qui peuvent impacter le comportement et les résultats des appels d'API.
Un changement potentiellement rétro-incompatible dans GraphQL se produit lorsque les modifications de l'API nécessitent que les applications clientes mettent à jour leurs requêtes ou leur logique pour maintenir la fonctionnalité. Exemples incluent :
-
Suppression d'un champ, d'un type ou d'un argument.
-
Renommer des champs, types ou arguments.
-
Modifier les valeurs par défaut des arguments d'une manière qui change les résultats attendus des requêtes ou mutations.
-
Modifier le type ou le comportement d'un champ d'une manière qui impacte la compatibilité. Par exemple, changer le type d'un champ (par exemple, de Int à String) ou modifier la nullabilité d'un argument (par exemple, de nullable à non-nullable).
Nous faisons de notre mieux pour éviter les changements potentiellement rétro-incompatibles. Cependant, dans le cas rare où un tel changement se produit, il sera communiqué aux clients comme expliqué ci-dessous dans Notification sur les API en Fin de Vie.
Ces changements peuvent se produire plus fréquemment pour les API Beta, mais sont rares pour les API GA.
Une API ou un champ marqué comme Obsolète indique que son utilisation n'est plus recommandée et qu'une meilleure alternative existe. Nous vous recommandons de mettre à jour les scripts et processus pour ne plus utiliser les API et champs obsolètes afin de maintenir le comportement et la fonctionnalité attendus.
Si une API ou un champ est planifié pour être retiré ou remplacé, elle suivra un processus de Fin de Vie (EoL). Ce processus comprend les étapes suivantes :
-
Marquage de l'API ou du champ comme obsolète
-
L'API ou le champ planifié pour être retiré est marqué comme Obsolète dans la Référence GraphQL de Cato Networks.
-
Ce label est accompagné d'un message, spécifiant une API ou un champ alternatif, le cas échéant, et la date planifiée de Fin de Vie.
-
-
Notifications de Fin de Vie
-
L'article Changements Potentiellement Rétro-incompatibles de l'API Cato et EoL est mis à jour avec la date précise à laquelle le schéma sera mis à jour avec le changement.
-
La période entre la notification et les changements de schéma est la suivante :
-
API GA : au moins 3 mois à l'avance et généralement 6 mois à l'avance
-
API Beta : généralement 2 semaines à l'avance
-
-
Pendant la période entre la notification de Fin de Vie et la date de Fin de Vie, les clients doivent mettre à jour le code client pour intégrer les changements au schéma GraphQL.
-
Les changements pour GraphQL qui ne sont pas rétro-incompatibles mais néanmoins significatifs, tels que de nouvelles API ou de nouveaux champs, sont annoncés dans l'article Cato API Changelog.
La Référence GraphQL de Cato Networks inclut toujours le schéma GraphQL complet, pris en charge et à jour.
0 commentaire
Vous devez vous connecter pour laisser un commentaire.