用于修补嵌套数据的 REST-API Json 结构

Question

假设您有一个 API 端点，它返回带有扩展国家/地区数据的用户数据：

获取用户/1

{
    UserName: "John Miller",
    Country: {
        Id: 1,
        Name: "Switzerland"
    }
}

现在您还可以使用相同的端点修改用户数据。我认为该结构有两种可能性来做到这一点。

补丁用户/1

{
    UserName: "John Miller",
    Country: {
        Id: 2
    }
}

补丁用户/2

{
    UserName: "John Miller",
    CountryId: 2
}

第一个版本将保留结构，但只需要 id。第二个不会嵌套，直接包含id。

有没有最佳实践或指南来做到这一点？

Answer 1

REST 的作用是将先验知识的需求集中到易于标准化的形式中。 -- 菲尔丁，2008年

换句话说，REST 的部分要点是以与其他人相同的方式做事，以便通用工具发挥作用。

如果您发送 HTTP PATCH 请求来修改 Web 服务器上资源的表示，那么您应该努力使用一组更改的标准化表示。

对于 JSON 文档，有两种标准化形式

json-patch+json 确实看起来像是一组更改；这些补丁文档是描述您想要进行的每个单独更改的操作列表

[
  { "op": "replace", "path": "/a/b/c", "value": 42 },
  { "op": "test", "path": "/a/b/c", "value": "C" }
]

合并补丁看起来更接近您已经尝试做的事情；该文档实际上是原始表示的精简版本，具有描述文档差异语义的标准化规则集。

{
  "a":"z",
  "c": {
    "f": null
  }
}

通常，对于 PATCH 语义有意义的资源，出于类似的原因，PUT 语义也有意义——因此您的 API 可能应该同时提供这两者，并允许客户端选择使用哪种方法来共享其更改。