RESTful API 应该返回带有代码的数据还是将代码转换为描述？答案

【问题标题】：Should a RESTful API return data with codes or translate codes into descriptions?RESTful API 应该返回带有代码的数据还是将代码转换为描述？
【发布时间】：2019-07-19 13:58:12
【问题描述】：

我正在开发一种将数据返回给最终用户的 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。

是否有标准或最佳实践可以提供一些指导？

【问题讨论】：

一切都取决于数据更改的速率，因为您可以只调用一次性别和国家/地区并将结果存储在客户端中以供以后重复使用，但如果安全性受到威胁，您应该使用第二个选项。第三个似乎是最能负担有效载荷的。
我会为调用者做一个选项。有选项 1 的默认值，但允许他们使用 URL 参数告诉您他们想要选项 2。并且保持一致：选项 2 具有 countryOfOrigin 的代码和值，但性别只有值，这是不一致的。作为一项规则，如果您不确定哪种方式，请同时使用这两种方式并让客户选择。

标签： javascript rest api

【解决方案1】：

是否有标准或最佳实践可以提供一些指导？

不是真的，只是有不同的权衡。

我在网络上能想到的最简单的类比是 java 脚本——你应该在页面中嵌入源代码吗？还是应该链接到源并单独下载？ “视情况而定”——当您想要对缓存策略进行细粒度控制时，拥有单独的资源非常好，但当缓存是一种责任而不是资产时，它就很糟糕了。

如 Preacher 所述，一种常见的方法是为不同的用例提供不同的资源。

另一种可能性是使用单一资源，但使用不同的表示（媒体类型）来支持不同的用例。

据我所知，这些只是缓解疼痛的不同方式。

【讨论】：

【解决方案2】：

您有几个可能的选择：

A.使用支持嵌入资源的 api 标准。

我倾向于对所有响应使用 HAL，但 HAL 并不是解决此问题的好格式。 JSON:API 可以更好地处理这种情况。它允许与响应一起发送关系，一个好的 JSON:API 客户端可以获取这些关系并将它们放入临时缓存中。

HAL 不适合这样做的原因是它没有很好的方法来消除多个关系的重复数据。 GraphQL 也能很好地处理这种情况，但它不是 REST。

B.攻击问题的真正原因。

你真正描述的问题是你担心会发出很多HTTP请求，有很多HTTP请求是一件坏事。

有几种方法可以解决这个问题。

使用 HTTP/2。由于 HTTP/2 有许多较小的请求，因此不再像以前那样成为问题。也许并没有你想象的那么痛苦。
使用 HTTP/2 推送。 Push 可以进一步优化这一点，并消除更多的延迟。
如果您的 API 很慢，请选择一种可以更快地响应 HTTP 请求的技术。您的框架是否对每个请求都有 100 毫秒的启动时间？这会非常引人注目。
使用出色的缓存标头。国家变化不大。您可以放置非常激进的Cache-Control 标头，让客户端保留标头的副本很长时间。这将特别有利于浏览器客户端（在服务器上运行的 HTTP 客户端往往不会大量使用缓存）。
使用良好的缓存代理或 CDN。这与 4 有关，并且可能使 3 变得不必要。

【讨论】：