オプションの有限セットへの追加。APIの重大な変更？

次の応答モデルを吐き出すHTTP APIエンドポイントを取ります。

{
    "type": "Dog",
    "name": "Jessi",
    ...
}

typeフィールドは次のいずれかであるとしてドキュメントに記載されているDog、CatまたはFish。

新しいオプションの追加は、たとえばRat、重大なAPIの変更と見なされますか？

有限リスト（開発者がオンにする可能性がある）にオプションを追加することは、APIの拡張または変更と見なされますか？

ドキュメントでこのフィールドがDog、Cat、またはFishの1つであると説明されている場合は、はい、別のタイプを追加すると、下位互換性のない方法でインターフェースが変更されます。APIのコンシューマが犬と猫を魚とは異なる方法で処理する特定のコードを記述したことは完全に考えられます。タイプが不明な場合、その消費者はあなたの応答をどうするかを知りません。しかし、これは、これらのプレースホルダタイプ「猫」と「魚」が実際の問題領域で何を表しているかに大きく依存します...

可能なタイプのリストへの変更が頻繁である場合、またはリストが有限でない場合、これをそのように文書化することは賢明です。ユースケースによっては、APIのエンドポイントとして可能なすべてのタイプのリストを公開するのが良い場合があります。これにより、APIバージョンを更新せずにタイプを追加または削除できることは明らかです。ただし、タイプが動的であるほど、APIコンシューマーがタイプ固有の何かを実行することが難しくなります。拡張性と使いやすさのどちらがより重要であるかは、ユースケースと問題ドメインによって異なります。

「Rat」が既存の操作から返された場合にのみ、問題が発生します。

既存の操作が「Rat」を返せない場合、この新しいオプションを追加しても効果はありません。