问题 我正在为我的公司编写API标准文档，并一直在尝试各种工具来增强我们的API生命力，今天我已经尝试了apisecurity.io的API定义安全验证工具， 它突出显示了我的一个POST操作中一个有趣的错误： “您尚未为应包含主体的响应定义任何模式。”链接：Response schema undefined并引用RFC 7231
已标记的API端点是返回的POST操作：201状态代码，位置标头，但没有正文。 （因此，该错误是因为该工具期望所有200s代码都具有除204外的主体）
研究 RFC7231 Section 6.3.2指出：
201（已创建）状态码表示请求已被执行 满足并导致一种或多种新资源 创建。标识请求创建的主要资源 通过响应中的Location头字段，或者如果没有Location 有效请求URI接收到该字段。
201响应有效负载通常描述并链接到 资源已创建。有关含义的讨论，请参见第7.2节。 验证标头字段（例如ETag和 最后修改，在201响应中。
当查看RFC7231 Section 4.3.3为POST操作定义的内容（如果该操作导致创建资源时）时，它会指出：
如果已在原始服务器上将一个或多个资源创建为 成功处理POST请求的结果，原始服务器 应该发送包含Location标头的201（已创建）响应 为创建的主要资源提供标识符的字段 （第7.1.2节）和描述状态的表述 请求，同时引用新资源。”
解释 当POST成功创建资源时：
前两个不足为奇，但第三个是我从标准要求的内容和先例获得的内容中发现相互矛盾的指导。 根据我的研究，所有知名的API创建者Google，Paypal，Github和Stripe都发送新创建资源的完整表示，而不是“请求状态的表示”。
RFC是否错误/已过时，最佳实践是我们应该返回完整的正文？ 我真的很重视其他人的意见，这些人曾经遇到过或对此进行了辩论，或者对对话感兴趣。
这似乎是一个琐碎的问题，但是我正在尝试记录最佳实践以类似于Zalendo来推动我们的一致性（除非返回204，否则似乎还会返回资源，但在这种情况下，客户不知道资源是否已创建或是否由POST更新了
要回答的问题 对于这种类型的响应机构，是否有遵循的标准？
相同的答案可能适用于PUT或POST获得200响应或PUT得到201响应。
答案 0 :(得分：2)
RFC是否错误/已过时，最佳实践是我们应该返回完整的正文？我真的很重视其他人的投入，这些人曾经遇到过或对此进行了辩论，或者对对话感兴趣
据我所知，RFC很好。
我认为您缺少的想法是Content-Location，这就是说我们可以在响应中使用元数据以标准化的方式弄清楚我们从服务器发送回的表示是
典型的“动作状态表示”可能看起来像
201 Created
Location: /api/new-things/12345
Your document can be fetched from /api/new-things/12345
相反，如果我们要发送所创建的新文档（资源）的表示，则需要在元数据中用信号表示。
201 Created
Location: /api/new-things/12345
Content-Location: /api/new-things/12345
Hi, I'm your new document, which can be fetched from /api/new-things/12345
大约-是的，您只需发送您在服务器上创建的新事物的表示，定制的客户端就可以理解。但是我们 还有一个问题，通用组件也需要理解对话，就它们而言，我们在谈论的是关于目标uri的对话，而不是关于{{1 }}。
HTTP标准是关于使用所有资源和组件通用的语义来描述正在发生的事情，而不是您的Java脚本的特定部分与您的特定URI进行对话。
答案 1 :(得分：1)
使用PUT或POST响应返回更新的资源表示形式而不是状态是很平常的事，您列出的API就是很好的例子。我想这样做的理由是为客户开发人员提供一些便利。
这不是HTTP规范中所描述的（由您提供的引号确认），并且这样做限制了API的丰富性。
例如，API可以接受符合架构的有效文档，但是执行业务规则评估或触发一系列事件。从业务规则的角度来看，响应状态可让客户知道发生了什么以及发生的任何问题。请注意，40倍的响应与客户端错误而非用户错误有关。
然后，我的观点是提供状态文档，其中列出有关此类处理的有用信息，包括
我不知道用于此目的的任何标准JSON文档格式（类似于application / problem + json见https://tools.ietf.org/html/rfc7807），但是也许一个有用的方法例如application / processing + json来加强该区域的API响应。