Kanorio
Kanorio 開発者

API リファレンス

バージョン管理と廃止

KanorioのAPIバージョン管理、破壊的変更の定義、および機能削除前の廃止通知プロセスについて説明します。

3つのAPIはすべて、URLで /api/v1 のようにバージョン管理されています。互換性のある変更は新しいバージョンを待たずに継続的にリリースされます。破壊的変更は、このページで説明するプロセスに従います。現在、APIは beta の段階にあります。構造は変更される可能性があり、すべての変更はまず 変更履歴 で告知されます。

互換性のある変更

これらは随時リリースされるため、許容できるクライアントを実装してください。

  • 新しいエンドポイント、操作、MCPツール、Webhookイベントの追加
  • 新しいオプションの要求フィールドおよびクエリパラメータの追加
  • 新しい応答フィールドの追加（不明なフィールドは無視してください）
  • 新しいエラーコードの追加（不明なコードは エラー で説明されているように、HTTPステータスに基づいて処理してください）
  • 新しい権限の追加、およびより多くの値を許可する緩和されたバリデーション

破壊的変更

これらは予告なしにリリースされることはありません。

  • エンドポイント、操作、ツール、フィールドの削除または名前変更
  • フィールドの型や意味の変更、またはオプションフィールドの必須化
  • エラーコードまたはそのHTTPステータスの変更
  • バリデーションの厳格化、または操作に必要な権限の変更

安定した操作において、破壊的変更は廃止プロセスを経て行われ、新しいURLバージョンが導入されても古いバージョンは少なくとも6ヶ月間利用可能です。現在のフェーズでは、破壊的変更はリリース当日に変更履歴に記載されます。

廃止の通知方法

操作が廃止される場合、すべてのチャネルを通じて即座に通知されます。

場所表示内容
レスポンスヘッダーDeprecation（廃止日）、Sunset（削除日）、および本ポリシーと代替案へのリンクを含むLinkヘッダー
OpenAPIオペレーションにおけるdeprecated: true、x-kanorio-sunset、およびx-kanorio-replaced-by
MCPツール説明の冒頭に[Deprecated, removed after …; use …]と表示
APIリファレンス削除日と代替案が記載された廃止バッジ
CLIstderrへの警告表示
メール過去30日間に該当オペレーションを呼び出したトークン所有者に対し、削除前に通知を送信
Deprecation: @1788134400
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://kanorio.com/en/developers/basics/versioning>; rel="deprecation"

操作は、廃止予定日（sunset date）を過ぎた後にのみ削除されます。

リリースフェーズ

各操作および各製品にはリリースフェーズがあります。リリースフェーズ を参照してください。

SDK、Elements、MCPのバージョン

  • @kanorio/sdk および @kanorio/elements はセマンティックバージョニングに従います。ボット保護、クローラーブロックリスト、リダイレクトなど、頻繁に変更されるルールはAPIから提供されるため、デプロイ済みのフロントエンドはアップグレードなしで最新の状態を反映します。
  • MCPサーバーは、serverInfo およびレジストリエントリでセマンティックバージョンを公開します。メジャーバージョンが上がった場合、既存の呼び出しの動作が異なる可能性があります。変更のたびに、変更履歴にバージョンが記載されます。