2

既存のRESTfulWebAPIのv2を作成しています。

応答は、オブジェクトのJSONリストであり、大まかに次の形式です。

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

v1で観察された問題の1つは、一部のクライアントが名前ではなく整数の位置でフィールドにアクセスすることです。これは、応答にフィールドを追加することを決定した場合（当初は互換性を維持する変更と見なしていた）、最後にフィールドを追加しない限り、クライアントのコードの一部が壊れることを意味します。それでも、他のクライアントのコードは、予期しない属性名に遭遇すると何らかの方法で失敗するため、とにかく壊れます。

v2でこれに対抗するために、すべての応答でフィールドをランダムに並べ替えることを検討しています。これにより、クライアントは位置ではなく名前でフィールドにインデックスを付けるように強制されます。

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

これはやや厄介に聞こえますが、新しいフィールドを追加できるという利点があります。これにより、クライアントが破損することはありません。これは、同じURLでv2.1、v2.3などに互換性のある更新を発行できることを意味します。つまり、少数のAPIバージョンを維持およびサポートするだけで済みます。

別の方法は、互換性を破るv3、v4を新しいURLで発行することです。これは、互換性のない多くのAPIバージョンを維持およびサポートする必要があることを意味します。これにより、少し薄くなります。

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

更新：最初のいくつかの応答は、問題を文書化した場合（つまり、フィールドが追加または並べ替えられる可能性があることをドキュメントに示した場合）、後でフィールドを追加または並べ替えたときにクライアントコードが壊れても責任を負わないことを指摘しています。残念ながら、これは私たちにとって適切なオプションではないと思います。何十もの組織が、実質的な経済的影響を伴う実際のトランザクションのためにAPIの機能に依存しています。これらの組織は技術指向ではありません。クライアント側での実装は、技術的な熟練度の全範囲をカバーします。私たちはすでにしましたv1のドキュメントでフィールドが追加または並べ替えられる可能性があり、明らかに機能しなかったというドキュメント。時間、経験、能力の不足により、多くのクライアントがまだ壊れたコードを記述しているため、v2を発行する必要があるためです。新しいフィールドを追加するとき。私が今インターフェースにフィールドを追加するとしたら、それは私たちへの十数の異なる会社のインターフェースを壊します、それは彼ら（そして私たち）が毎分お金を出血させていることを意味します。「彼らはドキュメントを読むべきだった！」と言って、変更を元に戻すことや修正することを拒否した場合、私はすぐに仕事を辞めます。「失敗した」パートナーを教育しようとするかもしれませんが、私たちが成長し続けるにつれて問題が毎月大きくなるため、これは失敗する運命にあります。私の質問は、パスで問題全体を体系的に先送りし、この状況が発生するのを防ぐことができるかということです。クライアントが何をしようとしても？私が提案するテクニックがうまくいくのなら、なぜ私はそれらを使うべきではないのですか？なぜ他のみんながそれらを使用しないのですか？

4

2 に答える 2

1

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

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

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

于 2012-02-08T03:57:28.857 に答える
1

説明されている手法を最大限に使用して実行することにしました。私のために水を保持している彼らへの異議は聞いたことがありません。異なる API バージョンに同じ URI を再利用することについての Brian の回答は、堅実で高く評価されている補足的なアイデア (賛成票付き) ですが、「ベストアンサー」とは言えません。私の元の質問。

于 2012-06-12T13:11:10.663 に答える