互換性とバージョニング

DUST API はパスでバージョン管理されており、すべてのエンドポイントは /api/v1 の下にあります。各バージョン内では API を継続的に進化させますが、厳格なルールに従います。変更は原則として追加のみとし、適切に実装されたインテグレーションを破壊する可能性がある変更には、必ず事前に非推奨期間を設けます。また、公開済みの OpenAPI 仕様が、常にその時点における契約の正式な定義となります。

このページでは、お客様のインテグレーションにとって「適切に実装されている」とは何を意味するのか、そしてその見返りとして DUST が何を保証するのかを定義します。

予告なく変更される可能性があるもの

以下の変更は後方互換性があるものと見なされます。これらはどのリリースにも含まれる可能性があり、お客様のインテグレーションはこれらを許容する必要があります。

新しいエンドポイントおよび既存のパスに対する新しい操作。
**新しいオプションのリクエストパラメーター、ヘッダー、本文フィールド。**既存のリクエストは変更せずに引き続き機能します。
**レスポンス内の新しいフィールド。**オブジェクトは時間の経過とともに拡張されます。
列挙型フィールドの新しい値 — 製品の成長に伴い、新しいイベントタイプ、状態、種類が追加されます。
**新しいエラーコード。**従来は汎用コードとして返されていた障害モードに対して追加されます。
**ドキュメント、エラーの message テキスト、フィールドの順序。**人が読める文字列は契約の一部ではなく、JSON メンバーの順序に意味はありません。

互換性を維持するインテグレーションの実装

クライアントが標準的な寛容な読み取り手法に従っていれば、上記のルールによる問題は生じません。

**認識できないレスポンスフィールドは無視してください。**予期しないメンバーがあっても決して失敗しないようにし、不明なフィールドを拒否する厳格なスキーマ検証は使用しないでください。
**不明な列挙値を許容してください。**処理できる値ごとに分岐し、処理できない値については問題なくフォールスルーするようにしてください。
**エラーでは message ではなく、必ず code に基づいて分岐してください。**コードは安定した識別子ですが、メッセージはローカライズされ、表現が変更される可能性があります。リクエスト規約を参照してください。
**ID とページネーションカーソルは不透明な文字列として扱ってください。**保存してそのまま再利用し、解析したり組み立てたりしないでください。
公開済みの仕様に記載されているものだけを呼び出してください。公開 OpenAPI 仕様に記載されていないエンドポイント、フィールド、動作には、互換性の保証はありません。

これらのルールに従うインテグレーションは追加的な変更の影響を受けず、以下の保証によって保護されます。

破壊的変更として扱うもの

以下に示す変更は、後述する非推奨化プロセスを経ずに、公開済みの /api/v1 の操作に対して行うことはありません。

エンドポイント、リクエストパラメーター、レスポンスフィールドの削除または名前変更。
フィールドの型または形式の変更。
オプションのリクエスト入力を必須にすること、または入力で受け付ける値を制限すること。
列挙型フィールドから値を削除すること。
既存の文書化された障害モードに対して返されるエラー code または HTTP ステータスの変更。
既存の操作に対して、より上位の認可階層または新しい権限を要求すること。
形状が変わらない場合でも、操作のセマンティクスを実質的に変更すること。

非推奨化

何らかの機能を廃止または再構成する必要がある場合は、最初に非推奨化します。

操作またはフィールドは、公開済みの OpenAPI 仕様で deprecated: true とマークされ、その非推奨化についてこのドキュメントに記載されます。
非推奨の機能は、告知から少なくとも 90 日間、変更されることなく引き続き機能します。
代替手段が存在する場合は、非推奨化の前またはその時点までに、文書化された代替手段を提供します。

バージョニング

新しいメジャーバージョンは、意図的にめったに導入しません。/api/v1 は追加的に進化します。互換性を保ったまま表現できない再構成が必要な場合にのみ /api/v2 を導入し、その場合も /api/v1 は、長期にわたり明示的に告知される移行期間を通じてサポートを継続します。前述の非推奨期間をもって削除されることはありません。