# バージョン管理と廃止

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

> Markdown version of https://kanorio.com/ja/developers/basics/versioning. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/basics/versioning.md

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

## 互換性のある変更

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

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

## 破壊的変更

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

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

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

## 廃止の通知方法

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

| 場所 | 表示内容 |
|---|---|
| レスポンスヘッダー | `Deprecation`（廃止日）、`Sunset`（削除日）、および本ポリシーと代替案へのリンクを含む`Link`ヘッダー |
| OpenAPI | オペレーションにおける`deprecated: true`、`x-kanorio-sunset`、および`x-kanorio-replaced-by` |
| MCP | ツール説明の冒頭に`[Deprecated, removed after …; use …]`と表示 |
| APIリファレンス | 削除日と代替案が記載された廃止バッジ |
| CLI | stderrへの警告表示 |
| メール | 過去30日間に該当オペレーションを呼び出したトークン所有者に対し、削除前に通知を送信 |

```http
Deprecation: @1788134400
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://kanorio.com/en/developers/basics/versioning>; rel="deprecation"
```

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

## リリースフェーズ

各操作および各製品にはリリースフェーズがあります。[リリースフェーズ](https://kanorio.com/ja/developers/basics/release-phases) を参照してください。

## SDK、Elements、MCPのバージョン

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