現在、JSON 形式の 4 つの変数を含むオブジェクトの配列を返す API エンドポイントがあります。
データのサイズは、レコード数に応じて 500kb から 5mb の範囲です。戻り値のサイズを小さくするために、オブジェクトからラベルを削除し、配列の配列を返すことを検討しています。
例えば
[{propertyone:123,propertytwo:456,propertythree:789,propertyfour:012},etc,etc,etc]
になるだろう
[[123,456,789,012]などなど]
次に、配列の位置 0 がプロパティ 1 と見なされることなどを文書化します。将来、この API が公開される時点があるかもしれません。名前をそのままにしておくことをお勧めしますか、それとも強制的な順序で文書化された API を提供することで十分でしょうか。
多くの場合、よく文書化された API が最良の API です。API の外部ドキュメントを持つことは重要ですが、返されるデータも同様にドキュメント化する必要があり、自己ドキュメント化データに勝るものはありません。
プロパティ名を削除すると、この自己文書化が完全に失われ、将来的にも自分自身を制限することになると思います. たとえば、部分的なデータのみを返したい場合、それらのプロパティ名なしでどのように表現しますか?
ドキュメントに加えて、JSON を返す場合は、消費者の環境に応じて、これらのプロパティを提供することで、自然に動作するモデルを提供できます。JavaScript を例として考えてみましょう。単純にレスポンスを JavaScript オブジェクトに解析する場合、基本的にクライアント側モデルが無料で実装されているため、API の操作が楽しくなります。
それにもかかわらず、スピードは重要であり、リターンのサイズを減らすためのさまざまな手段を検討することをお勧めします. 多くの場合、これに対する一般的な解決策はページ化された結果を提供することであり、クライアントがより多くのデータを必要とする場合は追加の要求を実行する必要があります。また、データの形状によっては、応答にGZIP 圧縮などの単純なものを使用することで大きなメリットが得られる場合があります。
API を設計している間、それを文書化し、説明どおりに機能する限り、通常は何でも十分です。ただし、成功するのは消費者に力を与える API です。