Cato APIとは何か

この記事は、Cato APIを使ってアカウント内の設定やアイテムを監視・設定するための入門を提供します。

概要

Cato APIは、Cato Cloudとのシームレスな統合を可能にする主な自動化インタフェースです。 Cato APIを使用して、効率的な運用ワークフローのセットアップ、配置と設定、包括的なステータスモニタリング、統計とデータ収集、およびネットワークとセキュリティ管理の効率化を行います。

Cato APIエンドポイントとスキーマ

APIエンドポイントとスキーマのURLは、Cato管理アプリケーション（CMA）がホストされている場所に特有です。 CMAアカウントおよびAPIエンドポイントとスキーマにURLに付加される<prefix>値が存在することがあります。

APIエンドポイントのURLは、https://api.<prefix>の形式です.catonetworks.com/api/v1/graphql2。

APIスキーマのURLは、https://api.<prefix>の形式です.catonetworks.com/api/schema。

APIエンドポイントのためのURL

プレフィックスがない場合（cc.catonetworks.com）、次のURLを使用します：https://api.catonetworks.com/api/v1/graphql2
プレフィックスがある場合（例：cc.us1.catonetworks.com）、以下のURLを使用します（異なるロケーションの場合はプレフィックスを変更してください）：https://api.us1.catonetworks.com/api/v1/graphql2

APIスキーマのためのURL

プレフィックスがない場合（cc.catonetworks.com）、次のURLを使用します：https://api.catonetworks.com/api/schema
プレフィックスがある場合（例：cc.us1.catonetworks.com）、以下のURLを使用します（異なるロケーションの場合はプレフィックスを変更してください）：https://api.us1.catonetworks.com/api/schema

APIスキーマドキュメンテーション

Cato APIはGraphQLに基づいて構築されており、RESTful APIツールおよびクライアントと完全に互換性のある直感的なインタフェースを提供します。 GraphQLは、必要なデータを正確にクエリする柔軟性を提供し、フェッチの過剰を削減し、効率を向上させます。

Cato APIのドキュメンテーションは、次のリンクから利用できます：Cato Networks GraphQL API リファレンス。これには：

スキーマの定義とドキュメンテーション
APIコールの例とそれに応じたサンプルレスポンス
GraphQL APIエンドポイントとインタラクティブなプレイグラウンドを使用したAPIの調査とテスト

APIライフサイクル

このセクションでは、特定のAPIの成熟度と利用可能性に基づいた異なるライフサイクルの段階について説明します。

すべての新しいAPIは、最初にベータ段階でリリースされます。ベータからGAへの移行は、APIが安定しており、運用準備が整っていることを確認するために、内部レビューと考慮に基づいて行われます。通常、ベータからGAへの移行には約一年を要します。

注：
以下で説明されているライフサイクルは、Cato Networks GraphQL API リファレンスで定義された正式なCato APIにのみ適用されます。それらには、リファレンスとして提供される追加のツールや例は含まれていません。
例えば、Cato GitHubアカウントで利用可能なオープンソースの例やユーティリティを含めません。これらのリソースは「そのまま」の形で提供され、さらなる開発、メンテナンス、またはサポートの保証や義務はありません。

API成熟度レベル

これらは、ライフサイクル段階の一部としてのAPIの成熟度レベルです：

ベータ: ベータ段階のAPIは機能が完備されており、運用環境で使用するのに適しています。ただし、ユーザーフィードバックや追加の考慮事項に基づいて変更が加えられる場合があります。これらの変更には、APIスキーマへの重要な変更が含まれることがあり、短期間の通知でクライアントコードの更新が必要になることがあります。
GA（一般提供）: GA段階のAPIは安定しており、プロダクション準備が整っており、長期的なサポートと後方互換性へのコミットメントが伴います。 APIスキーマへの重要な変更はまれであり、十分な時間をもって事前に通知され、クライアントコードの調整時間が与えられます。
ベータとして明示的にラベル付けされていないAPIはGAとみなされます。場合によっては、GA API内で個々のフィールド、タイプ、および入力がベータとしてマークされることがあります。

API利用可能性レベル

これらは、ライフサイクル段階の一部としてのAPIの利用可能性レベルです：

EA（早期利用可能）: EA段階のAPIは、より広範なリリース前にテストとフィードバックのために限定されたユーザーグループに提供されます。アクセスには特別な承認または条件が必要な場合があります。
段階的展開: クラウドベースサービスの業界標準のベストプラクティスに従い、Cato APIは安定性を確保し、パフォーマンスを監視するために段階的に展開され、利用可能性が時間とともにすべてのアカウントに拡大します。
EAまたは段階的展開としてマークされていないAPIは、完全に展開され、すべてのユーザーにアクセス可能とみなされます。

APIラベルの概要

このセクションでは、ドキュメンテーションにおける成熟度と利用可能性に基づいたAPIのラベルを要約しています。

ラベルがないAPIはすべてのアカウントに完全に利用可能であり、スキーマ変更はまれです。このような変更は数ヶ月前に予告されます。これらの変更についての詳細は、以下の破壊的なスキーマ変更の可能性をご覧ください。

EA
- CatoのEAプログラムに参加されるお客様のみが利用可能であり、参加ご希望の場合はea@catonetworks.comまでご連絡ください
ベータ
- スキーマに変更がある場合があります
- 重大な変更に関する短い通知期間、最短で二週間である可能性があります
- ベータAPIは完全な機能をサポートしています
ロールアウト
- これらのGA APIは、数週間にわたってすべてのアカウントに段階的に展開されます
- ロールアウト状態のAPI呼び出しは、アカウントに対してまだ利用可能でないため、エラーメッセージが表示される場合があります

破壊的なスキーマ変更の可能性

このセクションでは、CatoがGraphQL APIスキーマに変更を加える際に、APIコールの動作と結果に影響を与える可能性がある場合のことを説明します。

GraphQLでの破壊的変更の可能性とは何ですか？

GraphQLでの変更がクライアントアプリケーションにクエリやロジックの更新を求める必要がある場合、破壊的変更の可能性が生じます。例としては：

フィールド、タイプ、または引数の削除。
フィールド、タイプ、または引数の名前変更。
クエリまたはミューテーションの結果に変化を引き起こす引数のデフォルト値の修正。
互換性に影響を与えるフィールドのタイプや動作の変更。例えば、フィールドのタイプ変更（例：IntからString）や引数の非NULL性の変更（例：NULL値から非NULL値へ）。

破壊的変更の通知と管理

破壊的変更の可能性を避けるためできる限り努力しています。しかし、まれにそのような変更がある場合は、EoL APIの通知で説明されているように、顧客に通知されます。

これらの変更はベータAPIでより頻繁に発生する可能性がありますが、GA APIでは稀です。

廃止予定のAPI

廃止予定とマークされたAPIまたはフィールドは、使用が推奨されず、より良い代替手段が存在することを示します。期待される動作と機能を維持するために、スクリプトやプロセスを廃止予定のAPIやフィールドを使用しないように更新することをお勧めします。

EoL APIの通知

APIまたはフィールドの削除や置き換えが予定されている場合、廃止（EoL）プロセスを経ます。このプロセスには次の手順が含まれます：

APIまたはフィールドを廃止予定としてマーク
1. 削除が予定されているAPIまたはフィールドは、Cato Networks GraphQL API リファレンスで廃止予定とマークされています。
2. このラベルには、該当する場合は代替APIまたはフィールド、および計画されたEoLの日付を指定したメッセージが添えられています。
EoL通知
1. Cato API Potentially Breaking Changes and EoL記事は、スキーマが変更される具体的な日付で更新されます。
2. 通知とスキーマ変更の間の期間は次の通りです：
  - GA API：少なくとも3ヶ月前、通常は6ヶ月前
  - ベータAPI：通常2週間前
3. EoL通知とEoL日付の間の期間中に、顧客はクライアントコードを更新して、GraphQLスキーマの変更に対応することが期待されます。

非破壊的スキーマ変更

新しいAPIや新しいフィールドなどの非破壊的で依然として重要なGraphQLへの変更は、Cato API変更履歴記事で発表されます。

Cato Networks GraphQL API リファレンスには、最新でサポートされているGraphQLスキーマが常に完全に含まれています。