REST GET方法：能否return丰富资源列表？

Question

我在设计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 架构概念 (even the REST beyond CRUD)。

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

Answer 1

REST GET mehod: Can return a list of enriched resources?

TL;DR: 是的。

更长的答案...

成功的 GET 请求 returns 单个 resource 的表示，由请求目标标识。

用于创建资源表示的信息来自域模型中的多个实体，或数据库中的多行，或来自其他服务生成的报告……这些都是 实施细节。 HTTP transfer of documents over a network 应用程序不关心。

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

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

/A
/A?enriched
/B

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

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

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

Design is what we do to get more of what we want than we would get by just doing it.

REST GET方法：能否return丰富资源列表？

REST GET mehod: Can return a list of enriched resources?

api

rest

crud

restful-url