处理 POST 和 GET 之间的 RESTful 表示结构差异答案

【问题标题】：Handling RESTful representation structure difference between POST and GET处理 POST 和 GET 之间的 RESTful 表示结构差异
【发布时间】：2015-06-13 13:14:11
【问题描述】：

我正在设计一个 REST API，尽管搜索了许多最佳实践指南，但我找不到太多与处理表示之间差异的最佳实践相关的内容POST 所需的结构与 GET 返回的相同表示结构。

GET 的虚拟user 表示可能如下所示：

{
    "id": 1234,
    "created": "2012-04-23T18:25:43.511Z",
    "username": "johndoe@example.com",
    "name": "John Doe"
}

但是，POST 用于相同的虚拟user 表示不能指定某些属性（即id 和created）：

{
    "username": "johndoe@example.com",
    "name": "John Doe"
}

显然这是一个过于简化的示例，但鉴于用户无法指定某些字段（并且可能并不总是很明显哪些字段与所应用的方法相关）是 最佳实践 为每个创建单独的表示或期望最完整的版本并在服务器上透明地处理数据差异？

尽管拥有单一表示和处理差异服务器端显然很容易，但我担心如果不清楚可以指定哪些值（或使用PUT 更改），这对用户来说将是一个糟糕的体验例子）。如果倾向于创建单独的表示，是否有适用于表示定义的命名约定？

例如i_user 用于传入用户，o_user 用于传出用户。或user_full 和user_min 或user 和.user 等

更新：我过于简化的示例可能无法正确说明问题。想象一个具有 50 个属性的表示（例如，具有所有监视属性的服务器表示 - cpu、ram、temp、storage_drive_a、storage_drive_b、file_permission 等）在这 50 个属性中，30 个是只读属性，其中 20 个是可以设置。

【问题讨论】：

标签： rest representation

【解决方案1】：

首先，POST 方法的最终语义是由目标资源决定的，而不是像其他方法那样由 HTTP 协议决定，所以你的POST 方法可以做任何你想做的事情，只要你正确地记录它，并且你没有复制已经被其他方法标准化的功能。

因此，简而言之，POST 和 GET 方法具有不同的表示形式并没有错。

但是，在这种情况下寻求最佳实践是没有意义的，因为定义表示格式的是所使用的媒体类型，而不是方法，但互联网上大多数所谓的 REST API 都使用通用媒体一切和客户端的 -types 依赖于 URI 语义来了解他们正在处理的资源，这根本不是 RESTful。基本上，当事情正确完成时，您正在为 REST 中并不真正存在的问题寻求最佳实践。

因此，为了回答您的问题，您可以使用不同的媒体类型来表示不同的表示形式——例如，您的完整用户表示形式可能具有媒体类型 application/vnd.mycompany.user.full.v1+json，而简化的用户表示形式可能具有媒体类型 @987654326 @ -- 或者你可以有一个像application/vnd.mycompany.user.v1+json 这样的单一表示，并且你的这种媒体类型的文档可能会详细说明某些属性如何存在或不存在，或者如果没有提供可能有默认值。您的 POST 方法将需要一种媒体类型才能工作，并且如果客户端在 Content-Type 标头中发送任何其他内容，则会以 415 Unsupported Media Type 响应。同样，客户端可以使用 Accept 标头选择它想要的表示形式。

如您所见，当您真正在使用 REST 时，您所问的并不是问题，而不仅仅是将其用作 HTTP API 的流行语。

【讨论】：