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

Question

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

当前用户的 API 有这个路径 /user/:user_id 我的想法是为带有 url 的 POST 添加一个新的子路径： /user/: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 路径中也有一个类似枚举的子路径（valid/not_valid 等）似乎不是正确的做法。如果您将它包含在 JSON 有效负载中，它将位于架构下，并且您可以很好地对其进行版本化，以防您对枚举进行新添加。将它作为 URL 的一部分意味着客户端现在也必须知道新路径。

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