如何处理 REST API 中的更新？

Question

我想要一些关于使用 RESTful API 执行写入的方法的观点。对于这个例子，假设一个 Person 对象：

{
    "id": 1,
    "name": "Example Person",
    "addresses": [
        {
            "id": 11,
        }
    ],
    "friends": [
        {
            "id": 21,
            "name": "John"
        }
    ]    }

有一个 /people API 可以提供这样的对象。你可以 GET /people/123 来检索上面的例子。不过，我担心的是写作。传统上，通过 REST API 更新这样的对象是通过向 /people/123 发送带有对象新状态的 PATCH 或 PUT 来完成的。但是，您可能会在更新中执行一项或多项操作：

• 更改人名
• 更新现有地址
• 增加一个新地址
• 删除地址
• 更新现有朋友
• 将现有人员添加为新朋友
• 停止与某人成为朋友

每一个都是不同的动作，可能有不同的逻辑与之关联。例如，如果有人将您添加为朋友，您应该收到有关它的通知，而添加地址不应生成任何类型的通知。

在与 REST API 通信时，发送要采取的操作列表而不是仅发送对象的新状态并要求 API 确定用户打算基于此执行的操作是否有价值？

Answer 1

您的对象包含其他对象的列表。从技术上讲，您处理许多对象，而不是单个对象。因此，您的 JSON 结果不是 RESTful。REST 基于资源（您称之为对象），当它们不是组合时，您通常会将它们隔离开来。所以当你打电话

GET /people/123，这应该不是您提供您所呈现的例子。它应该提供这样的东西：

{ "id"   : 123,
  "name" : "Example Person" }

那是一种适当的人员资源，仅此而已。好友和地址将被设计为子资源，应该通过它们自己的 API 访问，例如：

GET /people/{id}/addresses
GET /people/{id}/friends

当有人将您添加为朋友时，您自然会有一个明确的资源调用。下面是一个例子：

POST /people/{id}/friends

这POST在正文中包含一位朋友的 ID，可能仅此而已。

旁注：当您稍后返回好友列表时，您只会获得好友 ID 列表，而不是他们的姓名等详细信息。原因是朋友是你要求的关系，而不是这个人的详细信息。如果您想要人员详细信息，则必须转到人员资源，例如：

GET /people/{friend-id}         [request for one friend]
GET /people?is-friend-of={id}   [request for all friends]

所有朋友的更新将如下所示：

PUT /people/{id}/friends

这PUT在正文中包含所有好友 ID 的列表。

您需要实现的业务逻辑将很容易链接到这些单个GET,POST和PUT请求。这应该使你的业务逻辑地狱变得清晰和容易。您甚至可能会发现不再需要一个PATCH。我已经学会了尽可能避免它，因为它造成的麻烦多于帮助。RESTful 指南PATCH在详细级别上过于模糊地处理动词。

我建议您更多地了解 RESTful 的含义，一旦您拥有一个真正是 RESTful 的 API，您就会发现处理业务逻辑很容易。好的开始：StackOverflow：什么是 RESTful 编程？