バージョンと互換性

APIのメジャーバージョンは/v1の1つだけで、機能は追加される一方です。今日書いた連携システムは、新しい機能が加わっても動き続けます。連携が依存しているものの名前が変わったり、削除されたり、意味が変わったりすることはありません。

バージョン番号

APIには1.62.0のようなバージョン番号があり、リリースのたびに変わります。

• エンドポイント、フィールド、イベントなど、何かが追加されたときはマイナー番号が上がります。
• 説明やメッセージのテキストを修正しただけで、他に何も変わらないときはパッチ番号が上がります。

アドレスが提供しているバージョンは、いつでも確認できます。

GET /v1/healthにもversionがありますが、これはそのアドレスで動作しているSursaのリリースのバージョンで、APIのバージョンではありません。

マイナーバージョンを選ぶことはできません。すべてのリクエストは現在のバージョンで処理されます。以下のルールがあるので、それで問題ありません。

/v1で変わりうること

次の変更は、どのマイナーバージョンでも行われることがあります。これらの変更で壊れないように連携システムを書いてください。

• 新しいエンドポイント。
• 新しい省略可能なパラメーターとリクエストのフィールド。それらを含まないリクエストは以前と同じように動作します。
• レスポンス、オブジェクト、イベントの新しいフィールド。
• レスポンスの列挙型の新しい値（カードの新しいステータス、新しいイベントタイプなど）。
• 新しいエラーコードと新しいレスポンスヘッダー。
• 緩和される上限（最大長が長くなる、範囲が広がるなど）。
• エラーのmessageのテキストや説明の言い回しの変更。

コードが許容すべきこと

• 知らないフィールドは無視する。レスポンスのフィールドが想定より多くても失敗しないようにし、それを拒否する厳格なスキーマを使わないでください。
• 知らない列挙値を受け入れる。レスポンスの列挙型はどれも値が増えることがあります。未知の値はエラーではなく「その他」として扱ってください。
• 知らないイベントタイプはスキップする。Webhookでもストリームでも同じです。
• 未知のエラーコードはHTTPステータスで処理する。エラーを参照してください。
• フィールドの順序に依存しない。JSONオブジェクトのフィールドの順序や、メッセージの正確なテキストを前提にしないでください。

/v1で変わらないこと

• パス、パラメーター、フィールド、列挙値の名前が変わったり、削除されたりすることはありません。
• フィールドの型は変わらず、フィールドが新しい意味（新しい単位など）を持つこともありません。
• 今日受け付けられるリクエストが、後で拒否されることはありません。
• 成功時のレスポンスのステータスコードは変わりません。
• エラーコードは意味を保ち、エラーレスポンスのdetailフィールドは形式を保ちます。
• イベントタイプの名前が変わったり、削除されたりすることはなく、そのdataはフィールドが増えるだけです。

破壊的変更

互換性のない変更がどうしても必要になった場合は、/v1と並ぶ新しいメジャーバージョン（/v2など）としてリリースされます。/v1は変更なしで動き続け、2つのバージョンが並行して稼働します。

ルートを廃止する場合：

1. 仕様でdeprecatedとマークされ、停止される日付とともに変更履歴に記載されます。
2. そのレスポンスには、Deprecation: trueとSunset: <date>のヘッダーが付きます。
3. 告知から少なくとも180日間は動作し続けます。そのルートをAPIキーで使っている組織には、少なくとも90日前に書面で通知します。
4. 廃止日を過ぎると、さらに90日間、コードapi.goneとともに410を返します。

ログやモニタリングでDeprecationヘッダーに注意してください。使っているルートが廃止されることを示す、最も早いサインです。

最新情報の入手

このポータルの変更履歴には、すべてのリリースが、追加されたものと非推奨になったものとともに記載されています。自社の連携システムを更新する前に、そのコードを、開発の基準にしたバージョン以降の記載と照らし合わせてください。