This article helps you get started with the Cato API to monitor and configure settings and items in your account.
Cato API is the primary automation interface for seamless integration with the Cato Cloud. Use the Cato APIs to set up efficient operational workflows such as deployment and configuration, as well as comprehensive status monitoring, statistics and data collection, and analytics to streamline your network and security management.
Cato APIs are built on GraphQL, offering an intuitive interface that's fully compatible with RESTful API tools and clients. GraphQL also provides the added flexibility to query exactly the data you need, reducing over-fetching and improving efficiency.
Cato API documentation is available at Cato Networks GraphQL API Reference, which contains:
-
Schema definition and documentation
-
Example API calls and corresponding sample responses
-
GraphQL API endpoint with an interactive Playground for exploring and testing the API
This section describes the different lifecycle stages based on the maturity level and availability of a specific API.
Every new API is initially released in the Beta stage. The transition from Beta to GA is subject to internal review and consideration to verify that the API is stable and production-ready. Typically, the transition from Beta to GA takes about one year.
Note
Note: The lifecycle described below refers only to the formal Cato API as defined in the Cato Networks GraphQL API Reference. It does not cover any additional tools and examples that may be provided as references.
For example, it does not cover the open-source examples and utilities available at the Cato GitHub account. These resources are provided “as is” with no warranty or obligation for further development, maintenance, or support.
These are the API maturity levels as part of the lifecycle stage:
-
Beta: APIs in the Beta stage are feature-complete and considered fully operational, making them suitable for use in production environments. However, they may undergo changes based on user feedback or additional considerations. These changes, including breaking changes to the API schema, may occur with short notice and require updates to client code.
-
GA (General Availability): APIs in GA are stable, production-ready, and come with long-term support and commitments to backward compatibility. Breaking changes to the API schema are rare and are announced well in advance to provide sufficient time for client code adjustments.
APIs that aren't explicitly labeled as Beta are considered GA. In some cases, within a GA API, individual fields, types, and inputs may be marked as Betas.
These are the availability levels for APIs as part of the lifecycle stage:
-
EA (Early Availability): APIs in EA are available to a limited group of users for testing and feedback before broader release. Access may require special approval or conditions.
-
Gradual Rollout: Following standard industry best practices for cloud-based services, Cato APIs are gradually rolled-out to ensure stability and monitor performance, with availability expanding to all accounts over time.
APIs not marked as EA or Gradual Rollout are considered fully deployed and accessible to all users.
This section summarizes the labels used for APIs in the documentation based on the maturity and availability levels.
APIs with no label are fully available to all accounts and there are rarely breaking schema changes. Any such changes will be announced several months in advance. For more about these changes, see below Potentially Breaking Schema Changes.
-
EA
-
Only available to customers that join Cato's EA program, to join, please contact us at ea@catonetworks.com
-
-
Beta
-
There may be changes to the schema
-
Limited notice for breaking changes, possibly as short as two weeks
-
Beta APIs support full functionality
-
-
Rollout
-
These GA APIs are being gradually rolled out to all accounts over a period of a few weeks
-
Calling an API in the Rollout status may result in an error message because that API is not yet available for your account
-
This section discusses when Cato makes changes to the GraphQL API schema that can impact behavior and results for API calls.
A potentially breaking change in GraphQL occurs when modifications to the API require client applications to update their queries or logic to maintain functionality. Examples include:
-
Removing a field, type, or argument.
-
Renaming fields, types, or arguments.
-
Modifying default values for arguments in a way that changes the expected results of queries or mutations.
-
Altering the type or behavior of a field in a way that impacts compatibility. For example, changing a field's type (e.g., from Int to String) or modifying an argument's nullability (e.g., from nullable to non-nullable).
We work as hard as possible to avoid potentially breaking changes. However, in the rare case that there is such a change, it will be communicated to customers as explained below in Notifying about EoL APIs.
These changes may occur more frequently for Beta APIs but are rare for GA APIs.
An API or a field marked as Deprecated indicates that its usage is no longer recommended, and a better alternative exists. We recommend that you update scripts and processes to no longer use deprecated APIs and fields to maintain expected behavior and functionality.
If an API or a field is planned for removal or replacement, it will go through an End-of-Life (EoL) process. This process includes the following steps:
-
Marking the API or Field as Deprecated
-
The API or field planned for removal is marked as Deprecated in the Cato Networks GraphQL API Reference.
-
This label is accompanied by a message, specifying an alternative API or field if applicable, and the planned EoL date.
-
-
EoL Notifications
-
The Cato API Potentially Breaking Changes and EoL article is updated with the specific date that the schema will be updated with the change.
-
The time period between the notification and the schema changes is as follows:
-
GA API: At least 3 months in advance and generally 6 months in advance
-
Beta API: Typically 2 weeks in advance
-
-
During the time period between the EoL notification and the EoL date, customers are expected to update the client code to accommodate the changes to the GraphQL schema.
-
Changes to the GraphQL that are non-breaking and still significant, such as new APIs or new fields, are announced in the Cato API Changelog article.
The Cato Networks GraphQL API Reference always includes the complete supported up-to-date GraphQL schema.
0 comments
Please sign in to leave a comment.