RESTful API 设计，在更新资源时区分 PUT 操作

Question

这是一个通用的 RESTful API 设计问题。我们正在尝试用最常见的方法解决以下情况。

我们有一个资源，比如说：/licenses/5123 资源有一个过期日期，需要更新为过期状态。当然，最简单的做法是只公开 expire_date 并让客户端将其设置为新日期，但这是不希望的。 为了更新资源，我们使用 PUT 方法并希望指定更新的类型。换句话说，更新操作是“过期”还是“扩展”或“随便”。

我考虑了几个选项：

1. 实现自定义 http 方法 - 但我不喜欢将 HTTP 协议扩展至超出其标准的范围
2. 添加action url参数并指定值：PUT /licenses/5123?action=expire
3. 由于 JSON 格式的请求正文中还有其他参数，因此将操作参数添加到 JSON 请求中。
4. 为更新类型实现自定义 http 标头

请分享您的意见和/或提供对可能描述此类案例的在线资源的任何引用。我无法想象这是一个独特的案例。

非常感谢！

Answer 1

通常首选选项 2 和 3。没有真正需要对 HTTP 操作或自定义标头进行自定义操作。

PUT 是您描述的更新许可证的合理操作方法。将更新的细节放在 JSON 请求正文中听起来很合理（选项 3），这就是我会做的。

Answer 2

选项 2 是我的首选。

我认为使用选项 2 是我常用的最佳实践，它干净、高效且可读。大多数时候，我都在努力争取可读性和可维护性，因为我将来可能不再是调试、修复或扩展代码的开发人员。

使用 HTTP 协议或标头做任何事情总是感觉像是在“破解”。我认为它已经超越了一切，并且需要比问题最可能值得付出更多的努力（这放弃了解决方案 1 和 4）。

选项 3 的一个潜在问题是您可能会将业务逻辑与数据混淆，从而导致耦合和潜在的升级问题。