Что такое API Cato

Эта статья поможет вам начать работу с API Cato для мониторинга и настройки параметров и элементов в вашей учетной записи.

Обзор

Cato API является основным интерфейсом автоматизации для бесшовной интеграции с Cato Cloud. Используйте API Cato для настройки эффективных рабочих процессов, таких как развертывание и конфигурация, а также для всестороннего мониторинга статуса, сбора статистики и данных, и аналитики для оптимизации управления вашей сетью и безопасностью.

Конечная точка и схема Cato API

URL для конечной точки и схемы API специфичен для местоположения, где размещен экземпляр приложения управления Cato (CMA). Может быть значение <prefix>, которое добавляется к URL вашей учетной записи CMA и к конечной точке и схеме API.

URL для конечной точки API имеет формат, https://api.<prefix>.catonetworks.com/api/v1/graphql2.

URL для схемы API имеет формат, https://api.<prefix>.catonetworks.com/api/schema.

URL для конечной точки API

Если нет префикса (cc.catonetworks.com), используйте следующий URL: https://api.catonetworks.com/api/v1/graphql2
Если есть префикс (например, cc.us1.catonetworks.com), используйте следующий URL (измените префикс для других местоположений): https://api.us1.catonetworks.com/api/v1/graphql2

URL для схемы API

Если нет префикса (cc.catonetworks.com), используйте следующий URL: https://api.catonetworks.com/api/schema
Если есть префикс (например, cc.us1.catonetworks.com), используйте следующий URL (измените префикс для других местоположений): https://api.us1.catonetworks.com/api/schema

Документация по схеме API

API Cato построены на GraphQL, предлагая интуитивно понятный интерфейс, который полностью совместим с инструментами и клиентами RESTful API. GraphQL также предоставляет дополнительную гибкость для запроса именно тех данных, которые вам нужны, уменьшая избыточный сбор данных и повышая эффективность.

Документация по API Cato доступна на Cato Networks GraphQL API Reference, которая содержит:

Определение схемы и документация
Примеры вызовов API и соответствующие примеры ответов
Конечная точка GraphQL API с интерактивной игровой площадкой для исследования и тестирования API

Жизненный цикл API

Этот раздел описывает различные этапы жизненного цикла на основе уровня зрелости и доступности конкретного API.

Каждый новый API первоначально выпускается на стадии бета-тестирования. Переход от Beta к GA подлежит внутреннему обзору и рассмотрению для подтверждения того, что API стабилен и готов к эксплуатации. Переход от Beta к GA обычно занимает около одного года.

Примечание

Примечание: Описанный ниже жизненный цикл относится только к официальному API Cato, как он определен в Cato Networks GraphQL API Reference. Он не охватывает дополнительные инструменты и примеры, которые могут быть предоставлены в качестве справок.

Например, он не охватывает примеры и утилиты с открытым исходным кодом, доступные на GitHub-аккаунте Cato. Эти ресурсы предоставляются "как есть" без гарантии или обязательства по дальнейшей разработке, обслуживанию или поддержке.

Уровни зрелости API

Это уровни зрелости API как часть этапа жизненного цикла:

Бета: API на стадии бета-тестирования полностью функционируют и считаются готовыми для использования в производственных средах. Однако они могут подвергаться изменениям на основе обратной связи пользователей или дополнительных соображений. Эти изменения, включая разрушающие изменения схемы API, могут происходить с коротким уведомлением и требовать обновления клиентского кода.
GA (General Availability): API в GA стабильны, готовы к эксплуатации и предоставляют долгосрочную поддержку и обязательства по обратной совместимости. Разрушающие изменения схемы API редки и объявляются заранее, чтобы предоставить достаточно времени для корректировки клиентского кода.

API, которые не помечены как Beta, считаются GA. В некоторых случаях в GA API могут быть отдельные поля, типы и входные данные, помеченные как Beta.

Уровни доступности API

Это уровни доступности API как часть этапа жизненного цикла:

EA (Early Availability): API в EA доступны ограниченной группе пользователей для тестирования и обратной связи перед более широкой рассылкой. Доступ может требовать специального разрешения или условий.
Постепенное развертывание: Следуя стандартным лучшим практикам для облачных сервисов, API Cato внедряются постепенно для обеспечения стабильности и мониторинга производительности, расширяя доступ для всех учетных записей со временем.

API, не помеченные как EA или Постепенное развертывание, считаются полностью развернутыми и доступными для всех пользователей.

Резюме меток API

Этот раздел резюмирует метки, используемые для API в документации, на основе уровня зрелости и доступности.

API без метки полностью доступны для всех учетных записей и разрушающие изменения схемы редки. Любые такие изменения будут объявлены за несколько месяцев заранее. Подробнее об этих изменениях смотрите ниже Потенциально разрушающие изменения схемы.

EA
- Доступно только клиентам, которые присоединяются к программе EA Cato, чтобы присоединиться, пожалуйста, свяжитесь с нами по ea@catonetworks.com
Бета
- Возможно изменения в схеме
- Ограниченное уведомление о разрушающих изменениях, возможно короткое, до двух недель
- Бета API поддерживают полную функциональность
Развертывание
- Эти GA API постепенно развертываются для всех учетных записей в течение нескольких недель
- Вызов API в статусе Развертывание может привести к сообщению об ошибке, так как этот API еще недоступен для вашей учетной записи

Потенциально разрушающие изменения схемы

Этот раздел обсуждает, когда Cato вносит изменения в схему GraphQL API, которые могут повлиять на поведение и результаты вызовов API.

Что такое потенциально разрушающее изменение в GraphQL?

Потенциально разрушающее изменение в GraphQL происходит, когда модификации API требуют от клиентских приложений обновления их запросов или логики для поддержания функциональности. Примеры включают:

Удаление поля, типа или аргумента.
Переименование полей, типов или аргументов.
Изменение значений по умолчанию для аргументов таким образом, который изменяет ожидаемые результаты запросов или мутаций.
Изменение типа или поведения поля таким образом, что это влияет на совместимость. Например, изменение типа поля (например, из Int в String) или изменение nullability аргумента (например, из nullable в non-nullable).

Объявление и управление потенциально разрушающими изменениями

Мы стараемся изо всех сил, чтобы избежать потенциально разрушающих изменений. Однако в редком случае, когда происходит такое изменение, об этом будет сообщено клиентам, как объяснено ниже в Уведомление об EoL API.

Эти изменения могут чаще происходить для Beta API, но редки для GA API.

Устаревшие API

API или поле, помеченные как Устаревшие, означают, что их использование больше не рекомендуется, и существует лучшая альтернатива. Мы рекомендуем обновить скрипты и процессы, чтобы больше не использовать устаревшие API и поля для поддержания ожидаемого поведения и функциональности.

Уведомление об EoL API

Если API или поле планируются к удалению или замене, они пройдут процесс завершения жизненного цикла (EoL). Этот процесс включает следующие шаги:

Пометка API или поля как устаревшего
1. API или поле, планируемые к удалению, помечаются как Устаревшие в Cato Networks GraphQL API Reference.
2. Эта метка сопровождается сообщением, указывающим альтернативный API или поле, если применимо, и планируемую дату EoL.
Уведомления об EoL
1. Статья Потенциально разрушающие изменения и EoL Cato API обновляется с указанием конкретной даты, когда схема будет обновлена с изменениями.
2. Временной промежуток между уведомлением и изменениями схемы следующий:
  - GA API: как минимум за 3 месяца и обычно за 6 месяцев заранее
  - Beta API: обычно за 2 недели заранее
3. В течение периода времени между уведомлением об EoL и датой EoL предполагается, что клиенты обновят клиентский код, чтобы учесть изменения в схеме GraphQL.

Неразрушающие изменения схемы

Изменения в GraphQL, которые не являются разрушающими и все же значительными, например, новые API или новые поля, объявляются в статье Changelog по API Cato.

Cato Networks GraphQL API Reference всегда включает в себя полностью поддерживаемую актуальную схему GraphQL.