破壊的変更に関するポリシー

概要

迅速な開発と安定性の維持を両立するため、ElevenLabsではAPIの範囲において破壊的変更と見なされるものについて、明確なガイドラインを定めています。ここでは、破壊的変更と見なす変更と見なさない変更を説明します。

レスポンスとスキーマの変更

APIレスポンスに対する追加的変更と削除的変更は明確に区別しています。レスポンスモデルへの新しいフィールドの追加は、破壊的変更とは見なされません。APIとのインテグレーションでは、APIクライアントが認識しないフィールドを無視し、APIレスポンスに対して厳格な型チェックを行わないことが求められます。ほぼすべての最新のAPIクライアントは、標準でこれに対応しています。

既存のレスポンスフィールドを削除したり、その構造を変更したりすることは破壊的変更です。クライアントアプリケーションが、これらのフィールドの存在と想定された形式の維持に依存している場合があるためです。

パラメータの変更

APIパラメータの変更には、厳格な互換性モデルを適用します。既存のエンドポイントに必須パラメータを追加すると、既存のクライアント呼び出しがバリデーションに失敗するため、常に破壊的変更となります。一方、任意パラメータ（デフォルト値があるもの、または任意であることが明示されているもの）の追加は、既存のクライアント呼び出しを変更せずに継続できるため、破壊的変更ではありません。同様に、パラメータの型や形式の変更、以前は任意だったパラメータを必須にする変更は、クライアントが期待する契約を変更するため、破壊的変更と見なされます。

エンドポイントとパスの変更

エンドポイントまたはAPIパス全体を削除すると、それらを呼び出すクライアントアプリケーションでエラーが発生するため、本質的に破壊的変更となります。エンドポイントが非推奨としてマークされる場合はありますが、影響を受けるすべてのユーザーに十分な周知を行わずに完全に削除することはありません。