平静的 POST 响应的“最佳”实践

Question

所以这里没有什么新内容，我只是想得到一些澄清，但似乎在其他帖子中找不到任何澄清。

我正在安心地创建一个新资源，说：

/books (POST)

有身体：

{
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

我知道我应该返回 201（已创建），其中包含新资源的 Location 标头：

Location: /books/12345

我自己似乎无法回答的问题是服务器应该在正文中返回什么。

我经常做这样的回应：

{
  id: 12345,
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

我这样做有几个原因：

1. 我为像 angularjs 这样的前端框架编写了 api。在我的 我正在使用角度资源的特殊情况，我经常需要 用于定位资源的 ID。如果我没有返回 id 我需要从位置中解析它的响应主体 标题。
2. 在所有书籍的 GET 中，我通常返回整个对象，而不仅仅是 身份证号。从这个意义上说，我的客户端代码不必区分 从哪里获取 id（位置标头或正文）。

现在我知道我确实处于灰色地带，但大多数人都说归还整个资源是“不好的”做法。但是，如果服务器更改/向资源添加信息怎么办？它肯定会添加 id，但也可能会添加其他内容，例如时间戳。如果我不返回整个资源，那么执行 POST，返回 id，然后让客户端执行 GET 来获取新资源真的更好吗？

Answer 1

返回新对象符合“统一接口 - 通过表示操作资源”的 REST 原则。完整的对象是所创建的对象的新状态的表示。

这里有一个非常优秀的 API 设计参考：设计实用的 RESTful API 的最佳实践

它包含您问题的答案：更新和创建应返回资源表示

它说：

防止 API 使用者必须再次访问 API 更新的表示，让 API 返回更新的（或创建的） 代表作为回应的一部分。

对我来说似乎很务实，它符合我上面提到的 REST 原则。

Answer 2

在更新时返回整个对象似乎不太相关，但我很难理解为什么在创建对象时返回整个对象在正常用例中是一个不好的做法。这至少对于轻松获取 ID 和获取相关的时间戳很有用。 这实际上是使用 Rails 搭建脚手架时的默认行为。

我真的没有看到仅返回 ID 并在之后执行 GET 请求来获取您可以通过初始 POST 获得的数据的任何优势。

无论如何，只要你的API是一致的，我认为你应该选择最适合你需求的模式。在我看来，没有任何正确的方法来构建 REST API。

Answer 3

发帖后我喜欢回复这样的内容：

Response
   .created(URI("/obj/$id"))
   .entity(TheNewObj())
   .build()

状态 201 - 已创建

标题位置 - 新对象的位置

实体 - 新对象

Answer 4

整个 REST 响应问题是一种高度固执己见的讨论，不存在最佳实践，但我越来越相信对每个休息呼叫的标准响应可能对您的客户有益。 RFC7807 确实描述了这样的响应。我并不是说在这里找到了答案，只是指出这可能是值得研究的事情。反映请求的内容似乎是多余的。只需确定 (200) 或创建 (201) 就足够了。尽管这是常识问题，但目前没有人掌握真相。

编辑：如lostintranslation注释：服务器可能会出于任何原因（标准化、计算等）更改有效负载，在这种情况下，在有效负载中反映资源的当前状态以便客户端向客户端显示是有意义的。用户。