rest - 处理 POST 和 GET 之间的 RESTful 表示结构差异

Question

我正在设计一个 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 个是可以设置。

Answer 1

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

所以，简而言之，对 POST 使用不同的表示并没有错。和 GET方法。

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

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

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