RESTful 执行两个操作的方法的名称

Question

在 API 我有门票资源，有两种方法：

1）获取工单状态（工单可为locked/unlocked）

GET /api/tickets/:id

2) 更新工单状态

PUT /api/tickets/:id with status=locked|unlocked

我需要的是在一次 API 调用中将状态检查与实际更新结合起来。而且我还需要知道状态是通过 API 调用更改的还是已经设置为所需的值。例如：

ticket_status = "unlocked"
PUT /api/tickets/:id/check_lock
changes ticket_status to "locked" and responses with "success"

ticket_status = "locked"
PUT /api/tickets/:id/check_lock
ticket_status is already "locked" so we response with "ignored"

对于反向操作我们可以有

PUT /api/tickets/:id/check_unlock

我知道我们在这里通过合并操作打破了单一责任原则，但这样做是为了减少 API 请求的数量，并且这将被非常频繁地调用。

所以我正在寻找好的名字，而不是那些丑陋的 "check_lock"、"check_unlock"，因为它们似乎相当含糊。

Answer 1

考虑到资源，我不会进行手术check_unlock。我建议：在 json 答案中获取 /api/tickets/:id 以及票证状态。即使您有两个 http 调用。

或者如果状态导致错误，您可以用错误 400 或类似的东西来回答。

Answer 2

使用类似

的东西

PUT /api/tickets/:id/check_lock

不推荐更新锁定状态（不是说不好的做法）。在阅读 check_something 时，人们通常会想到一种安全的方法，即不会期望它修改任何值。

您的示例 PUT 不是幂等的。即，对同一资源调用 PUT 两次会导致不同的结果。这与 HTTP Specification for PUT

矛盾

PUT request is defined as replacing the state of the target resource.

在您的情况下，最好使用 PATCH 更新零件票资源，如 RFC5789 or even https://www.rfc-editor.org/rfc/rfc6902

中所述

PATCH /api/tickets/:id/ HTTP/1.1
Host: example.org
Content-Type: application/json-patch+json

{ "op": "replace", "path": "/lock", "value": "unlock"  }

您可以选择在响应中使用 ETag 来表示资源是否已被修改。

或者只是带有消息正文的 HTTP 状态代码 200，其中您 return 资源是否被修改以及锁定状态的新值。

如果你想切换锁定状态，你应该使用类似“动作资源”的东西。在这种情况下使用 POST.

POST /api/tickets/:id/toggle_lock

因此，您可以 return 新锁状态以及它是否已更新，作为 HTTP 200 状态代码正文的一部分。

Answer 3

我会采取稍微不同的方法并使用 409 Conflict 状态代码。

The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.

会话成功：

PUT /api/tickets/123 { ... locked: true ... }
200 OK

已锁定会话：

PUT /api/tickets/123 { ... locked: true ... }
409 Conflict
POST /api/ticket-queue { // ticket data here }
201 Created

RESTful 执行两个操作的方法的名称

RESTful name for the method that does two operations

rest

restful-url