Web apiのコンシューマーがレスポンスの新しいフィールドを受け入れるようにする

Question

既存のRESTful Web APIのv2を作成しています。

応答が大体の形で、オブジェクトのJSONリストです：私たちはV1で観察してきた

[ 
    { 
    name1=value1, 
    name2=value2, 
    }, 
    { 
    name1=value3, 
    name2=value4, 
    } 
] 

一つの問題は、いくつかのクライアントが整数位置によって、代わりの名前でフィールドにアクセスすることです。つまり、最初に互換性維持の変更と見なしていたフィールドをレスポンスに追加すると、最後にフィールドを追加しない限り、クライアントのコードの一部が中断されます。それでも、予期せぬ属性名に遭遇したときに何らかの方法で失敗するため、他のクライアントはコードブレークをとらえます。

これをv2で処理するには、すべてのレスポンスでフィールドをランダムに並べ替えることを検討しています。これにより、クライアントは位置ではなく名前でフィールドのインデックスを作成します。

また、すべてのレスポンスにランダムに名前のついたフィールドを追加することも検討しています。これにより、クライアントは認識できないフィールドを無視します。

これは多少気味悪いとは言えますが、新しいフィールドを追加できるという利点があります。これは、これがクライアントを壊していないことを知って安全です。これは、同じURLでv2.1、v2.3などに互換性のあるアップデートを発行できることを意味します。つまり、&をサポートしているAPIバージョンの数を減らすだけです。

代替方法は、新しいURLで互換性を破るv3、v4を発行することです。つまり、互換性のない多くのAPIバージョンを&でサポートする必要があります。

これは悪い考えですか？もしそうなら、なぜですか？私が考えなければならない他の同様のアイデアはありますか？

更新：回答の最初のカップルは、私は問題を文書化した場合、私は、クライアントコードが破損した場合ときIその後を非難することはもはやいます（つまり、フィールドの追加や並べ替えすることができるドキュメントに示していない）ことを指摘しているフィールドの追加または並べ替え。残念ながら私はこれが適切な選択肢ではないと考えています。多くの企業の多くは、実質的な財務的影響を伴う現実世界のトランザクションのAPIの機能に頼っています。これらの組織は技術的に指向されておらず、結果的にクライアント側の実装は技術的な熟練のすべてをカバーしています。私たちはすでにをにしましたが、時間や経験や能力が不足しているために、多くのクライアントがv2を発行しなければならないので、フィールドがv1用のドキュメントに追加または並べ替えられ、新しいフィールドを追加するときに壊れるコードを書きました。インターフェースにフィールドを追加しようとすると、数十の異なる会社のインターフェースが壊れてしまいます。つまり、1分ごとに出血しています。変更を取り消したり修正したりすることを拒否した場合、「彼らはドキュメントを読んだはずです！」と言ったら、すぐに仕事から外れてしまいます。私たちは失敗したパートナーを教育しようとするかもしれませんが、私たちが成長し続けるにつれて問題が毎月大きくなるので、これは失敗することになります。私の質問は、全面的に問題を全面的に解決し、クライアントが何をしようとしてもこの状況が発生するのを防ぐことができるかどうかです。私が提案するテクニックがうまくいくなら、なぜ私はそれらを使わないべきですか？なぜ誰もそれを使用していないのですか？

Answer 1

私は、記載された技術を使ってmax。私は彼らに私のために水を保持することに異議を唱えていません。 Brianの答えは、さまざまなAPIバージョンに同じURIを再使用することであり、確かに高く評価されている補完的なアイデア（アップヴォート付き）ですが、それが「ベスト・アンサー」になることはできません。私の元の質問。

Answer 2

メディアタイプを「発展可能」にしたい場合は、その点をドキュメントで明確にしてください。同様に、フィールドの配置順序が保証されていない場合は、明示的にクリアするようにしてください。 APIのサンプルコードを提供する場合は、フィールドオーダーに依存しないようにしてください。

ただし、メディアタイプの異なるバージョンを維持する必要があるとしても、の場合、URIのバージョンを設定する必要はありません。 RESTを使用すると、バージョンに依存しない同じURIを維持できますが、HTTPコンテンツネゴシエーション（AcceptおよびContent-Typeヘッダー経由）を使用して、同じURIで異なるペイロードを提供できます。

したがって、新しいv2/v3/etcエンコーディングを受け入れることを明示的に希望しないクライアントは、それを取得しません。デフォルトでは、元のフィールドの順序で古いv1エンコーディングを返すことができ、これらの脆弱なクライアントアプリケーションはうまく動作します。しかし、新しいクライアント開発者は、Acceptを介して、新しいフィールドを見て喜んで、注文を気にしないことを（ドキュメントのおかげで）知っています。何よりも、同じURIを使用することができます（とすべきです）。覚えておいてください - このような異なるペイロードは、同じ基礎となるリソースの異なる表現なので、URI はと同じにする必要があります。