处理POST和GET之间RESTful表现结构差异的方法

Question

我正在设计一个REST API，尽管我查阅了许多最佳实践指南，但我没找到太多关于如何处理POST所需的表现结构与从GET返回的同一表现结构之间差异的最佳实践。

对于虚拟user表现形式的GET可能会像这样：

{
    "id": 1234,
    "created": "2012-04-23T18:25:43.511Z",
    "username": "[e-mail]",
    "name": "John Doe"
}

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

{
    "username": "[e-mail]",
    "name": "John Doe"
}

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

尽管只使用单个表示并在服务器端处理不同之处看似很容易，但如果用户无法清楚指定哪些值（或例如使用PUT更改哪些值），我担心这会给用户带来不好的体验。 如果倾向于创建单独的表示，是否可以应用命名规范来定义表示？

例如，i_user表示输入用户，o_user表示输出用户。或者user_full和user_min，或者user和.user等。

更新：我的过于简化的例子可能没有充分说明问题。 想象一个具有50个属性的表示（例如具有所有监视属性的服务器表示- CPU，RAM，温度，存储驱动器A，存储驱动器B，文件权限等）。 在这50个属性中，30个是只读属性，其中20个是可设置的值。

- tarka

Answer 1

首先，POST 方法的最终语义由目标资源决定，而不是由 HTTP 协议决定，就像其他方法一样，因此只要您适当地记录文档，并且没有复制已经被其他方法标准化的功能，您的 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 方法将需要一个媒体类型才能运行，并且如果客户端在 Content-Type 头中发送其他内容，则会响应 415 Unsupported Media Type。同样，客户端可以使用 Accept 标头选择其所需的表示形式。

正如您所看到的，当您真正实现 REST 时，您所询问的问题并不是问题，而仅仅是将其用作 HTTP API 的流行术语。

- Pedro Werneck