web-services - 集合、项、动词和REST接口(interface)设计 : what should POSTs return?

Question

我正在设计一个 REST 接口(interface)，我对插入/更新/删除动词应该返回什么(作为响应的内容)感到困惑。考虑用于 Invoice 实体的接口(interface)，可在 api/invoices 访问:

• GET/api/invoices 返回发票列表
• GET/api/invoices/123 返回 ID 为 123 的发票
• POST/api/invoices 添加一张新发票(ID 在服务器上生成)
• POST/api/invoices/123 更新 ID 为 123 的发票
• DELETE/api/invoices/123 删除 ID 为 123 的发票

很明显前两个方法应该返回什么，但是插入/更新/删除方法呢？一个明显的答案是 add 应该返回新创建的项目(即与 GET/api/invoices/id 完全相同的响应)，update 应该返回更新的项目(同样，与 GET 相同)和 delete 应该可能不返回任何内容(空内容)。这一切都是有道理的，而且是一致的。

但是当考虑不像发票实体那么简单的项目时，我的问题就开始了。例如考虑一个 add 请求，它不仅添加项目，而且实际上需要返回一些关于添加操作的额外信息:项目被接受(成功)，项目是重复的(成功信息), 该项目被忽略了(信息成功，我不会详细说明为什么)，该项目被拒绝(失败)。同样在我的例子中，我想返回额外的信息，比如为桶预先设置的“响应”信息到新添加的项目中。我考虑将所有额外信息作为带外信息(例如 200 范围内的额外状态代码，甚至是自定义 header )放在 http header 中，但这是一个 hack，并且“响应”部分实际上可以大于项目本身。所以现在我正在考虑 add 动词返回一个全新的类型，一个包含添加信息的项目(状态、响应、新项目的 ID，也许是整个新项目)。它当然可以完成工作，但我怀念以前的美妙对称。

这是一个好的做法吗(当添加一个类型为“foo”的项目时，返回的类型为“bar”)或者我会在 6 个月后回顾并拔掉我的头发，因为我让猫离开了袋子？如果我坚持“对 foo 的任何访问都会返回 foo，包括添加”，那么客户端将不得不在“添加”操作之后进行额外的调用以检索它真正感兴趣的信息(即“响应”)。

Answer 1

您的回复应该相当复杂。它不应与入站请求匹配。我们使用 JSON，并且除了对象之外还有一些额外的信息。

典型响应:

[{ "ID": the generated ID, "TYPE": the actual class name, "OBJECT": { the object } }]

POST 应该返回创建的对象。如果您有额外的信息(这不是一个好主意)，您可以在响应消息中携带它。

PUT 应该返回更新的结果。

DELETE 和 GET 一样，只能返回一个状态。

状态中的额外信息不是 hack——这就是状态代码如此开放的原因。

• 项目已被接受(成功)- 状态为 200 OK

• 该项目是重复的(信息成功)- 我不确定除了创建的最终对象之外您可能拥有什么信息，但这是 20 倍的地方 - OK WITH INFO 状态。

• 该项目被忽略(信息成功，我不会详细说明原因)- 这是模棱两可的。我不会称之为成功，我会称之为 40 倍——忽略。如果您不能详细说明原因，您可以称其为 20X - IGNORED。

• 项目被拒绝(失败)。这是一条普通的旧式 40X REJECTED 消息。