什么是正确的 RESTful 端点

Question

我有一个专门用于更新用户位置的 PUT 端点： /api/v1/user/{id}/location 和另一个 PUT 端点，用于更新用户忙碌状态的另一个属性 /api/v1/user/{id}/availability

我想知道这是否是一种反模式，因为我最终会在两者上更新用户的状态。也就是说，我应该只有一个 PUT 端点： /api/v1/user 更接近 RESTfulness？

我更喜欢使用单独的端点来保证我只更新一个用户属性，而合并使我失去了额外的清晰度和目的性。谢谢！

Answer 1

在您的场景中，HTTP“PATCH”似乎是更好的选择。

https://www.restapitutorial.com/lessons/httpmethods.html

如果不更新整个资源，而是只更新特定资源的几个部分，则上页建议使用 PATCH 方法与 PUT。

例如，可以在服务器上发送和处理带有 JSON 正文的补丁，其中包含要更新的特定属性。请求正文将包含位置或可用性或两者。

最后，针对特定资源 ID 请求 PATCH 操作，即 /api/v1/user/{id}。

Answer 2

您需要专注于您想要执行的操作，而忘记端点。操作看起来像 moveUser(userId, location)、makeUserBusy(userId)、makeUserAvailable(userId)。如果您检查，这些更改资源状态并且它们都是幂等的，显然不是删除，因此您对所有这些的HTTP方法将是PUT或PATCH。知道动词后，您可以考虑资源的名词。 （虽然这是 REST 的预算版本，因为在真实版本中，URL 并不重要。由于 HATEOES 约束，客户端应该能够发现它。但假设我们这样做是为了更好地理解日志中的 URI。）使用 PATCH，您可以进行部分修改，因此名词可以是用户本身或用户状态，例如 PATCH /api/v1.0/user/{userId} {"location":"..."} 或 PATCH /api/v1.0/user/{userId} {"isBusy":true} 就足够了。在 PUT 的情况下，您可以更深入地更改属性：PUT /api/v1.0/user/{userId}/location "..." 或 PUT /api/v1.0/user/{userId}/isBusy true。两者都是允许的，也可以。您需要做的就是记录它们，特别是如果您不想满足 HATEOAS 约束。