RESTful API應該返回帶有代碼的數據還是將代碼轉換為描述？

Question

我正在開發一個API，它將向最終用戶返回數據。 在我的服務器端模型中，我使用許多具有關聯的查找表的代碼來查找描述和與該代碼相關的其他相關屬性。

我很好奇在返回數據方面是否有“最佳實踐”。 這里的選項是：

選項1：返回碼並為查找列表提供API

在這種情況下，您可能會遇到以下情況：

//An API call to get a person
let person = await this.dataService.getPerson(1); //performs fetch
//{id: 1, first: "Micky", last: "Mouse", gender: 1, countryOfOrigin: "US"}

//An API call to get lookups -- returned as Map();
let genders = await this.dataService.getGenders();
let countries = await this.dataService.getCountries();

//Now I can do the following to get the definition
let gender = genders.get(person.gender);
let country = countries.get(person.countryOfOrigin).description;

 console.log("gender.description");
 console.log("country.description");
 console.log("country.isoA3");

選項2：返回完全填充的對象

//API call to get a person
let person = dataService.getPerson(1);
//{id: 1, 
   first: "Micky", 
   last: "Mouse", 
   gender: "Male", 
   countryOfOrigin: {
      code: "US",
      description: "United States of America",
      isoA3: "USA",
      isoN3: 840
    }
  }

選項3：使其自引用

我知道有一個選項，countryOfOrigin可能是指向給定國家/地區的另一個API調用的鏈接。 但是，在我的情況下，大多數用戶將要求大量人員而不是單個人員，並以列表形式顯示這些人員。因此，如果用戶必須查詢1000個人，這將對服務器造成很大的沖擊然后ping服務器1000次以獲取每個countryOfOrigin。

是否有標准或最佳實踐可以在此提供一些指導？

Answer 1

是否有標准或最佳實踐可以在此提供一些指導？

並非如此，這只是權衡取舍。

我在網絡上想到的最簡單的類比是Java腳本-您是否應將源代碼嵌入頁面中？ 還是應該鏈接到源並單獨下載？ “這取決於”-當您希望對緩存策略進行細粒度的控制時，擁有單獨的資源非常有用，但是在緩存時，它的糟糕是一種責任而不是資產。

如Preacher所述，一種常見的方法是為不同的用例提供不同的資源。

另一種可能性是使用單個資源，但是使用不同的表示形式（媒體類型）來支持不同的用例。

據我所知，這些只是緩解痛苦的不同方法。

Answer 2

您有兩種可能的選擇：

答：使用支持嵌入資源的api標准。

我傾向於對所有響應都使用HAL，但是HAL並不是解決此問題的好方法。 JSON：API可以更好地處理這種情況。 它允許發送關系以及響應，一個好的JSON：API客戶端可以獲取這些關系並將它們放在臨時緩存中。

HAL不適用於此的原因是它沒有消除重復關系的好方法。 GraphQL可以很好地處理這種情況，但它不是REST。

B.找出問題的真正原因。

確實，您正在描述的問題是您擔心會發出許多HTTP請求，而擁有許多HTTP請求是一件壞事。

有幾種方法可以解決這個問題。

1. 使用HTTP / 2。 對於HTTP / 2，具有許多較小的請求已不再是一個問題。 也許沒有你想的那么痛苦。
2. 使用HTTP / 2推送。 推送可以進一步優化這一點，甚至可以消除更多的延遲。
3. 如果您的API速度很慢，請選擇一種可以更快響應HTTP請求的技術。 您的框架是否對每個請求都有100毫秒的啟動時間？ 這將是非常明顯的。
4. 使用出色的緩存頭。 國家變化不大。 您可以放置​​非常激進的Cache-Control標頭，讓客戶端將標頭的副本保留很長時間。 這將特別有利於瀏覽器客戶端（服務器上運行的HTTP客戶端往往不使用太多緩存）。
5. 使用良好的緩存代理或CDN。 這與4相關，並且可能使3不必要。