混合 REST 与非 RE​​STful API 调用

Question

我正在编写一个 RESTful API。在大多数情况下，一切都很好，但在少数情况下，当我不处理资源时，事情开始崩溃。虽然有一百万种方法可以解决我面临的问题，但我正在寻找一些反馈，哪些是最理想的。

为简单起见，我们将 API 称为 timer。

• 一个用户一次只能有 1 个活跃的timer。
• API 有 2 个功能端点 start 和 stop。
• 当用户starts 计时器时，他们POST 一些与timer 相关的数据会创建一个新的timer，只要他们还没有运行timer。
• 在timer 上调用stop 会更新timer 以将其标记为非活动状态。

我目前的设置如下：

开始计时器：

POST /api/v1/timer
Body: [
    'thing1' => 'something',
    'thing2' => 'somethingelse
]

Response: 204

停止计时器：

PUT /api/v1/timer/stop
Body:

Response: 204

由于用户只能有 1 个 timer 处于活动状态，因此返回 timer id 似乎没有意义，就像在更传统的 CRUD 调用中那样。

我读过一些帖子，建议在 stop 调用上使用 POST 方法来触发停止，而不是 PUT。我想这也是有道理的......当你不处理传统资源时，这真的很糟糕。

当然，我也可以重写它以返回 timer 资源，但对我来说，这增加了客户端在想要停止（或删除）活动计时器时必须跟踪 timer id 的开销.

我们将不胜感激。

Answer 1

想想你将如何在网站上实现这一要求。

您将查看一些特定于当前用户的网页。会有一个标记为开始的链接。你会得到那个链接，它会弹出一个表单，让你能够覆盖与启动计时器相关的默认参数。

当您提交表单时，浏览器会根据 HTML 表单处理规则构造一个请求。由于这不是一个安全的操作，该方法可能是一个帖子，并且表单数据将被 application/x-www-form-urlencoded 到消息正文中。

由于更改计时器的状态可能会更改原始页面的表示，因此表单可能会告诉您提交 POST。对 POST 请求的成功响应将告诉浏览器使其缓存的原始页面表示无效。

当您重新加载该页面时，“开始”链接将消失，取而代之的是“停止”链接。该链接的操作大致相同 --> 单击链接会将您带到一个表单，将表单提交回原始页面，使先前的表示无效。当您重新加载页面时，计时器关闭，开始链接再次可用。

GET /DarthVaderYellowMerrigold

GET /DarthVaderYellowMerrigold/start
POST /DarthVaderYellowMerrigold
GET /DarthVaderYellowMerrigold

GET /DarthVaderYellowMerrigold/stop
POST /DarthVaderYellowMerrigold
GET /DarthVaderYellowMerrigold

您可能会采取各种措施来清理它（例如，返回新的表示以响应成功的 POST，并使用适当的 Content-Location 标头，以便客户端不需要获取数据） ，但基本思想是合理的。

以机器可读的方式执行此操作，您就拥有了一个 REST API。

这样做主要意味着记录机器应该如何理解每个链接的用途。 "要转到开始计时器表单，请查找此链接；要转到停止计时器表单，请查找该链接"。

您可能不会单独使用 HTTP 和 URI，但将 HTML 替换为例如超媒体 JSON 类型之一是合理的。或者将链接放入 HTML 标头中，而不是在表示中。

当然，HTML 的直接优势是您可以“手动”操作 API，并确保使用您最喜欢的桌面浏览器时一切正常。权衡取舍比比皆是。