REST API 响应状态代码 - 搜索返回单个结果的 GET

Posted 2023-04-13

【中文标题】REST API 响应状态代码 - 搜索返回单个结果的 GET

【英文标题】：REST API response status code - search GET that returns a single result

【发布时间】：2021-08-16 15:43:21

【问题描述】：

如果我们有一个搜索 GET REST API 端点，它为当前登录的客户返回一个或零个结果，我想知道正确的响应状态代码是什么，例如：

api/subscriptions?productId=1

根据规范，客户可以订阅一次，也可以不订阅产品。

据我所知，根据惯例，无论结果是否存在，这都应该是200 结果（与返回对象列表的搜索端点的逻辑相同）。我认为在这里返回404 是不正确的，因为这个结果只是可能存在的资源？

我知道这种查询甚至可能看起来不合常规，因为它的目的不仅是获取订阅，而且是检查它是否存在。

我的想法是将响应模型包装在一个对象结果中，状态码为200：

public class ActiveSubscriptionModel

    public bool HasActiveSubscription  get; set; 
    public SubscriptionModel Subscription  get; set; 

【问题讨论】：

204 没有合适的内容。状态代码可能有点主观。

【参考方案1】：

TL;DR: 200 是正确的状态码

---

据我所知，根据惯例，这应该是 200 结果，无论结果是否存在（与返回对象列表的搜索端点的逻辑相同）。

不是根据约定，而是根据specification -- 200 是状态码，表示HTTP 响应的有效负载是所请求的resource 的representation。

“您要求我提供由 /api/subscriptions?productId=1 标识的网页的表示形式，这就是我要发回给您的内容。” -- 200。

请注意，状态代码（即transfer of documents over a network 域的元数据）与您的 域中文档的语义毫无关系。

---

204 没有合适的内容。状态代码可能有点主观。

不是一个很好的选择。 204 宣布响应的有效负载长度为零字节，并暗示用户代理不应离开当前视图。

比较我们“应该”对网络浏览器的期望：一个长度为零的 200 响应将遍历“空”网页的视图； 204 响应会让我们查看之前的视图（可能会混淆查看网页的人）。

204 的亮点在于我们在一个符合 HTTP 的编辑器中，对资源进行本地更改并与服务器共享它们。我们点击编辑器上的保存按钮，表示被 PUT 到服务器，服务器按原样接受它，我们可以在不刷新页面的情况下继续编辑。

（您会看到205 Reset 类似——适用于我们使用网络表单进行数据输入时）。

---

选择适当状态代码的部分技巧是记住服务器不控制客户端 - 我们不一定要向我们控制的 java 脚本代码发送响应。因此，我们希望确保我们发送的信息让每个人都能以同样的方式理解。

【讨论】：

感谢您的澄清。我已将您的答案选为“已接受”，因为它让我有足够的洞察力做出决定。