用于更新资源的单个属性的 REST Api 设计

Question

根据我正在工作的项目的规范，需要公开一个 API，允许将用户实体的状态更改为 [ VALID |无效 | TO_VALIDATE].

用户的当前 API 具有此路径/用户/:user_id我的想法是为带有 url 的 POST 添加一个新的子路径:/用户/:user_id/状态

因为我只想更新一个值，您会发现哪种设计选择是最好的？

• 使用请求的正文 (JSON)
• 使用查询字符串，例如/user/:user_id/status?value=VALID
• 创建三个端点，每个端点对应一个可能的状态值:
  • /user/:user_id/status/valid
  • /user/:user_id/status/not_valid
  • /user/:user_id/status/to_validate

谢谢。

Answer 1

如果状态是不可查询的，那么您甚至可以将其作为用户实体本身的一部分，例如/user/:user_id 并执行 PATCH(使用 JSON 负载)来更新状态。通常，如果子路径可以作为子资源自行查询或独立更新，人们更喜欢嵌套路径。因此，如果有人需要用户的状态，他不会期望它出现在/user/:user_id 的 GET 结果中吗？或者他是否需要对/user/:user_id/status 进行另一个 GET 调用？我认为/status 路径可能不是一个好主意。

此外，如果您现在添加诸如状态之类的内容，那么如果您将来需要更新姓名、地址等，将会发生什么情况。我们不想继续为每个字段添加新的子路径，对吗？在 URL 路径中也有一个类似枚举的子路径(有效/无效等)似乎不是正确的做法。如果您将它包含在 JSON 有效负载中，它将位于模式下，并且您可以很好地对其进行版本控制，以防您向枚举添加新内容。将它作为 URL 的一部分意味着客户端现在也必须知道新路径。

另一方面，您还应该考虑 API 的可用性。我在设计 REST API 时通常遵循的一条经验法则:我希望我的客户在 2 分钟左右的时间内与我的 API 集成，并且我必须尽量减少他需要知道的事情的数量才能成功集成。所有标准和规范都可能次于可用性。