rest - 如何为非资源实体设计REST API

Question

我正在开发一个非常简单的电子商务应用程序，其中 UI/html 通过一组 RESTful API(具体来说是 ASP.NET Web API)与服务器通信。

当正确遵循 REST 时，API 会公开资源。这在处理我的域对象(例如产品、用户等)时效果很好。

但有一些功能不遵循此模式。例如，当用户输入订单号时，我想检查这是否是有效的订单号。现在我可以在订单 API 上执行简单的 GET 操作，并返回找不到无效订单

GET http://myhost.com/api/orders/SomeOrderNumber -> http 404

但是这是正确的方法吗？如果我想返回错误代码和消息怎么办？ (这显然不是订单对象的一部分)

那些不属于我的域的实体怎么办？例如我想根据一些参数和条件验证邮政编码。我真的不想要这样的东西

GET http://myhost.com/api/postcodes/SomePostCode -> validation message

如果我想获取当前登录用户的数量，应该公开什么样的 API？如果有人可以向我指出任何早期的帖子或有用的文档，那将非常有帮助。

Answer 1

1. GET 无法正确返回空响应。即使是空响应也意味着 204 No Content 状态。您应该返回 404 Not Found，并且您可以在错误消息正文中解释为什么该订单号无效。

2. 无论某个实体是否属于您的域的一部分，这对客户端都应该是透明的。同样，您描述的示例是正确的方法。

3. 要返回当前登录的用户数，您需要在服务器上存储 session 状态，而这样做一开始就不是 RESTful。您可能希望拥有一个可以通过查询进行过滤的集合资源，并且可以按照上次看到用户的时间进行过滤。例如:

   GET /api/users?last_seen_since=2014-10-31 0:00:00

在响应中，您可以有一个元数据字段或 header ，指示该查询的总大小。