我应该使用哪种资源来保留我的 API RESTFul？

Question

我正在构建一个 API 以允许 API 的客户端发送通知以提醒用户更新订单状态。到目前为止，有两个通知：

当用户未将订单标记为已收到时；
当用户尚未将订单标记为完成时。

我想构建此 API 以便轻松扩展到与订单相关的其他通知，但为此 API 的客户端保留一个简单的 URI。如何定义我的资源以保持我的 API RESTFul?

我正在考虑采用以下结构之一：

选项 1:

POST: /api/ordernotification/receive/{id}
POST: /api/ordernotification/complete/{id}

选项 2（省略资源的状态，post 代替）:

POST: /api/ordernotification/?id={id}&statusID={statusID}

编辑

选项 2.1（按照@Jazimov 的建议保留明确的 URI）：

POST: /api/ordernotification/{statusID}/{id}.

哪个选项更合适？一个选项比另一个选项有什么优势吗？或者还有其他我没有想到的选择吗？

Answer 1

我认为，要更新已插入记录的状态，您的端点应该是 PUT 而不是 POST。

您可以使用

PUT: /api/ordernotification/:id/status/

有客户json数据

 {
     "status": "your_status"
 }

端点根据请求数据更新记录。

Answer 2

如果我没理解错的话，你有两种ordernotifications：通知receive和通知complete。如果它们是两个独立的数据模型，那么我认为嵌套它们是个好主意（即 table 称为 ReceiveOrderNotification 和 CompleteOrderNotification）。如果是这种情况，那么您可能希望完全公开两个不同的端点，例如 POST /api/receiveordernotification 和 POST /api/completeordernotification.

但我认为这还不够，因为订单通知之间可能存在如此多的重叠相似之处。现在，选项 2 更像是 GET，因为您使用的是查询参数，所以对于第一个选项，让我们将它们折叠成这样：

POST: /api/ordernotification/

然后传递一些 JSON 数据来创建通知

{
    "orderId": "orderId",
    "userId": "userId",
    "prompt": "not marked received/not marked done"
}

我还删除了 /{id}，因为当您 POST 创建一个全新的东西时，通常还没有创建 id。即使客户端正在创建一个 id 并将其发送到 API，最好让它保持打开状态，这样您的 API 就可以以自己的方式处理创建一个新的、独特的资源.

这是 RESTful 是因为 POST 使用某些数据点创建资源 ordernotification。您的第一个选项使操作本身成为一种资源，但后端的任何数据模型中可能都没有表示。为了尽可能 RESTful，您的 API 端点应代表数据库域（tables、集合等）。然后让控制器根据请求中发送的数据选择要使用的服务方法。否则 REST 端点会预先公开所有逻辑，并成为一长串无法维护的端点。

Answer 3

我会遵循这些思路

POST /api/order/1234/notifications/not-received
POST /api/order/1234/notifications/not-completed

以后可以通过

访问

GET /api/order/1234/notifications/not-received
GET /api/order/1234/notifications/not-completed

或者

GET /api/order/1234/notification/8899

对于 URI 的语义丰富程度没有真正的限制，因此您不妨利用这一点并明确说明。

我应该使用哪种资源来保留我的 API RESTFul？

Which resource should I use to keep my API RESTFul?

api

rest

restful-url

restful-architecture

asp.net-web-api