rest - 用于创建资源的 REST API 补丁方法

Question

使用 JSONAPI 1.0 标准设计 API 没有 PUT 方法。创建资源只有 POST 方法，部分更新只有 PATCH 方法。我们有用户可以向服务器发送请求的用例，如果资源不存在，则必须创建否则更新。RFC 将此类方法描述为 PUT。接下来引用提到的 RFC 5789 标准 PATCH 有信息：

“如果 Request-URI 不指向现有资源，则服务器可以创建新资源，具体取决于补丁文档类型（是否可以在逻辑上修改空资源）和权限等。”

使用 PATCH 方法来更新和创建资源是个好主意吗？应该使用哪个标准来支持 PUT 和 PATCH 方法（可能是 OpenApi）？

如何解释 RFC 描述？

此致

标签： restapi

Answer 1

我们有用户可以向服务器发送请求的用例，如果资源不存在，则必须创建否则更新。

在这种情况下，正确的答案几乎肯定是POST您对集合资源的请求，并让服务器找出“正确”的事情要做。

可以通过向代表资源集合的 URL 发送 POST 请求来创建资源。

用于PUT创建资源假定客户端可以/应该猜测新资源的正确标识符应该是什么。如果我们不授予客户端该权限/控制权，则请求需要改为使用稳定的目标 uri，并且服务器计算对其他资源的副作用。

在 JSON:API 中，服务器可以控制新项目的 URI 选择。

POST /photos HTTP/1.1
Content-Type: application/vnd.api+json

...

HTTP/1.1 201 Created
Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000

如果 API 支持 PUT 语义，则等效更改将类似于

PUT /photos/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Content-Type: application/vnd.api+json

HTTP/1.1 201 Created

但是 JSON:API 已经决定PUT 还不够有趣。在字里行间，作者决定PUT应该保留它，直到更多的实现证明他们理解 HTTP 规范。

因此，您可以对集合进行 POST 以进行创建，并在项目上进行 PATCH 以进行部分或完全替换。

这反过来意味着如果客户端不/不能知道资源已经存在，它应该 POST 到集合。反过来，服务器应该知道资源可能已经存在，并做一些明智的事情（替换资源的表示，将客户端重定向到资源等）。服务器如何实现这一点将是一个实现细节。

研究 REST HTTP 方法的 Internet 处理我从未见过 PATCH 可用于资源创建，因此我很惊讶 JsonApi 放弃了 PUT 方法。

PATCH 当然可以用于资源创建——参见RFC 5789

如果 Request-URI 不指向现有资源，则服务器可以创建新资源，具体取决于补丁文档类型（是否可以在逻辑上修改空资源）和权限等。

这是一个不常见的选择，因为 PUT 语义更适合该用例。选择支持 PATCH 但不支持 PUT 很奇怪。

我很惊讶 JsonApi 放弃了 PUT 方法

我也很惊讶。

可以通过注册一个新的配置文件来解决您的问题，鼓励社区为您需要的语义采用通用模式。