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

Question

从我正在使用的项目的规范来看，需要公开一个API，允许将用户实体的状态更改为[VALID | NOT_VALID | TO_VALIDATE]。

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

因为我想只更新一个你认为最好的设计选择的值吗？

• 使用请求的正文（JSON）
• 使用查询字符串，例如/用户/？：USER_ID /状态值= VALID
• 为每个可能的状态值创建三个端点：
  • /用户/：USER_ID /状态/有效
  • /用户/：USER_ID /状态/ not_valid
  • /用户/：USER_ID /状态/ to_validate

感谢。

Answer 1

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

此外，如果您现在添加类似状态的内容，如果您将来需要更新名称，地址等，会发生什么。我们不想继续为每个字段添加新的子路径吗？在URL路径中有一个类似枚举的子路径（有效/ not_valid等）似乎不是正确的做法。如果将它包含在JSON有效负载中，它将属于模式，如果您对枚举进行新的添加，则可以很好地对其进行版本化。将它作为URL的一部分意味着客户现在也必须知道新路径。

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