具有二元状态的资源的RESTful设计

Question

我有一个资源，它本质上是一个简单的CRUD文档，它有一个小的变化，它可以“切换”到“已同步”状态，其中- in而不是使用它自己的当前值，它现在返回它现在与之同步的“父”文档的值。

我正在尝试找到一种RESTful方法来对此进行建模。该资源具有指示此状态Synchronzied = true/false的属性和指示它与哪个资源同步的ParentId属性。

一种选择是只允许在PUT更新期间更改它，但感觉不太正确，因为这不是文档的一部分，而在某种程度上是关于文档的元数据。我还考虑过将请求的状态作为参数传递的POST /document/{id}/synchronized请求。

不过，这两种情况都不太对劲。第一种感觉有点笨拙，因为它感觉就像我只为一个值解析提交的数据，如果我们在同步，其余的基本上都被丢弃了。在第二种情况下，仅仅为一个属性创建嵌套资源是错误的。

Answer 1

这里的一种解决方案是使用两种不同的资源类型-完整文档和从属文档-通过MIME类型来区分。例如，对于整个文档，您可以使用application/vnd.mysite.document，当您只是链接到另一个文档时，可以使用application/vnd.mysite.documentlink+json。

要制作从属文档，请执行以下操作：

PUT /document/1234
Content-Type: application/vnd.mysite.documentlink+json

{"parent": "/document/1"}

要制作完整文档，请执行以下操作：

PUT /document/1234
Content-Type: application/vnd.mysite.document

Hello, I am a document full of stuff.

然后，您可以通过返回文档或将303 (请参阅其他)重定向到父对象来响应GET请求。

Answer 2

作为对同步资源的GET的响应，您可以考虑返回302/303，并将Location标头设置为父资源。但随后允许对相同的同步URI执行PUT，将重定向替换为被传输的实体，然后在后续的GET响应中返回该实体。如果您希望允许客户端将一个实体切换回已同步状态，您可以通过对子URI执行POSTing操作，将包含所需父实体的URI的请求体发送到该子URI。您甚至可以通过允许客户端发布任何URI来发现偶然的用例，而不仅仅是一小部分已知父项的id。

GET /child
    200 OK
    {foo: bar}

POST /child
{parent: /some/other}
    200 OK

GET /child
    302/303
    Location: /some/other

PUT /child
{foo: baz}
    201 Created

GET /child
    200 OK
    {foo: baz}

Answer 3

您已经了解了大多数常见的选项，但是请考虑使用HTTP PATCH method。我已经通过AJAX在Firefox和Chrome上成功地使用了它。PATCH方法指定要应用于文档的一组更改，而不是(通过PUT)替换整个文档。

(如果只想检索文档的一部分，请考虑使用GET指定Range header。您需要定义字节范围以外的内容来处理XML或JSON文档--请参阅有关range units的详细信息。)

显然，这两种解决方案都假设有一个愿意使用的客户机和服务器--如果您不能在请求的两端都支持API，那么这两种解决方案都不会有太大的成功。