更新对象图的REST API设计

Question

我正在设计一个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”的“IDs”，但我担心PUT/PATCH的对象图与GET不同，使得API难以学习和记忆。因此，另一种选择是按以下方式请求PUT/PATCH：

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

这将产生与先前更新相同的更改，不会更改对象图。但是，它没有明确向 API 使用者表明只能更新 "IDs"。

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

- Johnny Oshika

Answer 1

我认为你应该在GET和PUT请求中保持相同的结构。为什么？因为将JSON / XML数据映射到对象是非常常见的，大多数（如果不是全部）执行实际映射工作的软件都最适合JSON模式始终相同。

因此，您的Web服务应该接受以下JSON代码：

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

然而，它不必考虑国家名称，可能仅关注国家ID。

- Crozin