用于更新对象图的 REST API 设计答案

【问题标题】：REST API Design for Updating Object Graph用于更新对象图的 REST API 设计
【发布时间】：2012-04-22 21:54:45
【问题描述】：

我正在设计一个 REST API，并且正在寻找更新对象图的推荐最佳实践。我的问题最好用一个例子来解释，所以假设我有一个 GET 资源，如下所示：

URI：/people/123

这个 URI 返回一个像这样的对象图：

{
    "name":"Johnny",
    "country":{"id":100,"name":"Canada"},
    "likes":[
        {"id":5,"name":"Fruit"},
        {"id":100,"name":"Sports"}
    ]
}

当允许 API 使用者更新此资源时，您希望如何通过 PUT 或 PATCH 更新对象？更新“name”属性非常简单，但我不确定“country”或“likes”，因为消费者只能更改与其他对象的关系而不能创建新对象。

这是请求更新的一种方式：

{
    "name":"Bob",
    "countryId":200
    "likeIds":[3,10,22]
}

此更新会将资源更改为以下内容：

{
    "name":"Bob",
    "country":{"id":200,"name":"United States of America"},
    "likes":[
        {"id":3,"name":"Cars"},
        {"id":10,"name":"Planes"},
        {"id":22,"name":"Real Estate"}
    ]
}

这种设计明确而明确地要求消费者只更新“Person”的“ID”，但我担心 PUT/PATCH 的对象图看起来与 GET 不同，这使得 API 难以学习并记住。所以另一种选择是按如下方式请求 PUT/PATCH：

{
    "name":"Bob",
    "country":{"id":100},
    "likes":[
        {"id":3},
        {"id":10},
        {"id":22}
    ]
}

这将产生与先前更新相同的更改，并且不会改变对象图。但是，API 使用者并没有明确说明只能更新“ID”。

在这种情况下，推荐哪种方法？

【问题讨论】：

标签： api rest object-graph

【解决方案1】：

在我看来，对于 GET 和 PUT 请求，您应该保持相同的结构。为什么？因为将 JSON/XML 数据映射到对象是很常见的，如果 JSON 模式始终相同，大多数（如果不是全部）执行实际映射的软件效果最好。

所以您的网络服务应该接受以下 JSON 代码：

{
    "name":"Joe",
    "country":{"id":200,"name":"United States of America"},
    "likes":[
        {"id":5,"name":"Fruit"}
    ]
}

但它不必考虑国家/地区名称，可能只关注国家/地区 ID。

【讨论】：