REST API设计：先执行，然后撤消

Question

我正在尝试编写一个api点，将状态更改为“已暂停”，这看起来很简单

PUT /api/artefacts/:id/status {"status": "SUSPENDED"}

但是现在，毫无悬念，不是直接的，它应该检查工件是否在其他地方使用并返回新状态，可能是"UNUSED" or "USED"，没有“ ACTIVE”或“ UNSUSPENDED”

那么正确的方法是什么？

POST /api/artefacts/:id/unsuspend

或 PUT /api/artefacts/:id/status {"status": "UNSUSPEND"}处于不存在的状态，并且让系统的行为与简单的补丁有所不同吗？

---

编辑将PATCH更改为PUT

在进一步研究之后，我对解决方案并不满意，并且在追求卓越的同时，我做到了这一点：

POST /api/artefacts/:id/status {"action": "Suspend"}
POST /api/artefacts/:id/status {"action": "Unsuspend"}

• 没有动词，因此我将状态发布为
• 间接状态隐藏在体内
• 状态现在可以接受任何操作，而不仅仅是暂停和取消暂停，它可以是“发布”，“隐藏”，“撤消”等。

请分享您对更新建议的输入

Answer 1

PATCH仅用于更改资源上的属性，而不必像使用PUT那样提供所有属性。

在我看来，您可以对资源执行两个操作，分别是暂停和取消暂停。尤其是后者是一个实际的动作，需要检查系统中其他地方有关资源的某些内容，并根据该检查返回状态。在那种情况下，我不认为PATCH是我会使用的方法。

我可能会像这样对资源的两个动作进行建模

POST /api/artefacts/:id/suspend

和

POST /api/artefacts/:id/unsuspend

这向客户端更清楚地表明，这些是对资源的非幂等操作，而不仅仅是属性更改。