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不必要。