API設計 - 在數組中排序返回數據

Question

我目前有一個API端點，它返回一個對象數組，每個對象包含JSON格式的4個變量。

數據的大小從500kb到5mb不等 - 取決於記錄的數量。爲了減少返回的大小，我們正在考慮從對象中移除標籤，並返回一組數組。

E.g.

[{propertyone：123，propertytwo：456，propertythree：789，propertyfour：012}等，等，等]

將成爲

[[123456789012]，等等，等等，等等]

然後，我們會記錄該數組的位置0，以考慮propertyone等。將來此API可能會公開時會出現一個點。是否認爲更好的做法是保留名稱，或者以強制執行的命令爲已記錄的API提供服務。

Answer 1

記錄良好的API通常是最好的API。爲您的API提供外部文檔非常重要，但是您返回的數據也需要記錄在案，並且沒有任何數據會影響自我記錄數據。

我想通過刪除屬性名稱，你會完全失去這個自我記錄，你最終可能會在未來限制自己。例如，只考慮想要返回部分數據，如果沒有這些屬性名稱，您將如何表示它？

除文檔外，如果您要返回JSON，然後根據消費者的環境，提供這些屬性可以爲他們提供一個自然的模型。以JavaScript爲例，如果他們簡單地將您的響應解析爲JavaScript對象，則它們基本上具有免費實現的客戶端模型，這將使​​您能夠使用API​​來獲得樂趣。

儘管如此，速度是重要的，我會建議尋找不同的措施來減少回報的大小。常見的解決方案是提供分頁結果，如果需要更多數據，則需要客戶端執行其他請求。另外，根據您的數據的形狀，您可以通過在回覆中使用諸如GZIP compression之類的簡單內容來獲益良多。

在設計一個API時，只要你記錄它並按照描述工作，通常任何事情都足夠了。但是，賦予消費者權力的API是成功的。