バックエンドコードのJSONに余分なフィールドを追加する

Question

バックエンドからのJsonレスポンスに追加フィールドを追加する予定でした。 このAPIは多くのクライアントによって消費されるため、すべてのクライアントを変更することはできません。 これは、既存のフロントエンドクライアントの機能に影響しますか？

Answer 1

この影響は、クライアントの既存のでしょうか？

我々は、すべてのクライアントを監査することなく知ることができません。

この影響は、クライアントの既存のでしょうか？

クライアント

いいえ、それはないはずですが、...

この影響は、既存のだろうか？

はい。一部のクライアントは、JSONドキュメントのフィールドを列挙することがあります（RPCスタイルのAPI、メタプログラミング、またはリフレクションで一般的です）。彼らは完全に壊れているかもしれないし、そうでないかもしれないが、この場合、結果は不特定である。

だから私は何をしますか？安全なはずの新しいフィールドを追加する

1. ：

は、2つのオプションがあります。全体的なリスクが低いという期待に基づいて最小限の労力をかけ、フィールドを追加するだけです。 （IMOこれは実用的なオプションです。）

あなたは、フィールドを追加する新しいAPIを作成するのいずれか/ V2 /またはので、新しいクライアントがオプトインすることができ、新たなデータと古いに余分なフィールドを持っているいくつかの他のエンドポイントクライアントは影響を受けません。 （これは防弾オプションです。）

新しいAPIがリリースされる前に、あなたはまた、新しいフィールドがオプトインクライアントが要求に特定のヘッダに合格した場合、人々は互換性のために彼らのクライアントをテストできるようにすることができます

（基本的に＃2ですが、一時的です）。

適切なソリューションは、APIクライアントの性質と数によって異なります。たとえば、組み込み機器に多数のクライアントがある場合は、おそらく既存のAPIを変更しないでください。 OTOHクライアントがすべて共通ライブラリを使用してAPIとやりとりして簡単に更新できる場合は、まずクライアントライブラリを更新してから、クライアントの大半が更新された後にAPIを更新することができます。

私はこれを簡単に前進することはできますか？

はい、「クライアントが既存のエンドポイントに新しいフィールドを追加することを期待する必要があります」というAPI契約書/設計文書がある場合、これは本質的に安全な操作になります。

全体的な姿勢が下位互換性、廃止予定、およびアップグレードにどのようなものかを検討することは良いことです。今後は、あなたとあなたのクライアントの両方があなたのAPIがどのように進化するかについて同じ期待を持っているように、これを書き留めてください。このようにして、設計文書を参照してこの決定を下すことができ、クライアント作成者はこれを参照して適切なプログラミング上の決定を下すことができます。