时间戳

首页 > 解决方案 > REST GET方法：可以返回丰富资源的列表吗？

api - REST GET方法：可以返回丰富资源的列表吗？

问题描述

我在设计 REST API 时有疑问。

考虑我的服务器中有一个包含两个元素的资源“客户”，如下所示：

[
   {
      name : "Mary",
      description : "An imaginary woman very tall."
   },
   {
      name : "John",
      description : "Just a guy."    
   }
]

我想创建一个端点，它将接受带有查询的 GET 请求。该查询将提供一个带有值的参数，该值将使算法计算该文本在其所有参数中出现的次数。

所以如果我们抛出这个请求：

获取 {baseURL}/customers?letters=ry

我应该得到类似的东西

[
       {
          name : "Mary",
          description : "An imaginary woman very tall.",
          count : 3
       },
       {
          name : "John",
          description : "Just a guy.",
          count : 0
       }
    ]

Count 参数不能包含在资源方案中，因为这取决于查询中提供的值，因此必须丰富响应对象。

我没有得到我的资源列表，而是一个修改后的资源。

虽然它保持了 GET 方法的幂等条件，但我看到它脱离了 REST 架构概念（甚至是 CRUD 之外的 REST）。

它仍然是 RESTful API 中的有效端点吗？还是我应该创建一个名为“ratedCustomer”的新资源？

标签： apirestcrudrestful-url

解决方案

REST GET方法：可以返回丰富资源的列表吗？

TL；DR：是的。

更长的答案...

成功的 GET 请求返回由请求目标标识的单个资源的表示。

事实上，用于创建资源表示的信息来自域模型中的多个实体，或数据库中的多行，或来自其他服务生成的报告……这些都是实现细节。网络应用程序上的文档的 HTTP传输无关紧要。

这也意味着我们可以拥有多个资源，在它们的表示中包含相同的信息。想想那些重复彼此信息的“维基百科页面”。

Web 上的资源标识符在语义上是不透明的。所有这三个标识符都被理解为不同的资源

/A
/A?enriched
/B

我们人类查看这些标识符可能期望在语义上更/A?enriched接近于，但机器不会做出这样的假设。/A/B

/A?enriched使用不同的模式甚至不同的内容类型来生成表示是完全合理的（就 HTTP 应用程序而言，/A作为 HTML 文档和/A?enriched图像是完全合理的）。

因为机器不在乎，所以您在如何设计资源和资源标识符方面拥有额外的自由度，您可以使用这些自由度来享受额外的好处，包括设计易于实施或易于记录的模型, 或易于交互, 或易于监控, 或....

设计是我们所做的，以获得比我们仅仅做的更多的我们想要的东西。

推荐阅读