在REST API中使用PUT进行更新时，我是否应该允许发送完整的结构？ [英] Should I allow sending complete structures when using PUT for updates in a REST API or not?

问题描述

我正在设计REST API，我想知道处理资源更新的推荐方法是什么。更具体地说，我将允许通过资源上的 PUT 进行更新，但我应该在 PUT 请求？

I am designing a REST API and I wonder what the recommended way to handle updates to resources would be. More specifically, I would allow updates through a PUT on the resource, but what should I allow in the body of the PUT request?

1. 始终是资源的完整结构？


2. 始终是子部分（已更改） ）资源结构？


3. 两者的组合？

例如，获取资源 http://example.org/api/v1/dogs/packs/p1 。
此资源上的 GET 将提供以下内容：

For example, take the resource http://example.org/api/v1/dogs/packs/p1. A GET on this resource would give the following:

Request:
GET http://example.org/api/v1/dogs/packs/p1
Accept: application/xml

Response:
<pack>
  <owner>David</owner>
  <dogs>
    <dog>
      <name>Woofer</name>
      <breed>Basset Hound</breed>
    </dog>
    <dog>
      <name>Mr. Bones</name>
      <breed>Basset Hound</breed>
    </dog>
  </dogs>
</pack>

假设我要添加一只狗（Sniffers the Basset Hound），我会支持：

Suppose I want to add a dog (Sniffers the Basset Hound) to the pack, would I support either:

Request:
PUT http://example.org/api/v1/dogs/packs/p1
<dog>
  <name>Sniffers</name>
  <breed>Basset Hound</breed>
</dog>

Response:
HTTP/1.1 200 OK

或

Request:
PUT http://example.org/api/v1/dogs/packs/p1
<pack>
  <owner>David</owner>
  <dogs>
    <dog>
      <name>Woofer</name>
      <breed>Basset Hound</breed>
    </dog>
    <dog>
      <name>Mr. Bones</name>
      <breed>Basset Hound</breed>
    </dog>
    <dog>
      <name>Sniffers</name>
      <breed>Basset Hound</breed>
    </dog>
  </dogs>
</pack>

Response:
HTTP/1.1 200 OK

或两者兼而有之？如果建议通过结构的子部分支持更新，我将如何处理删除（例如当狗死亡时）？通过查询参数？

or both? If supporting updates through subsections of the structure is recommended, how would I handle deletes (such as when a dog dies)? Through query parameters?

推荐答案

是的，始终发送资源的完整表示。否则，你会（根据PUT的通用定义和用法）用这只狗替换包。

Yes, always send the complete representation of the resource. Otherwise, you would (according to common definition and usage of PUT) replace the pack with just this one dog.

但是，您可能需要考虑以下事项：

However, you might want to consider the following:

• 使用XML名称空间或其他版本控制方法（例如？version = 2） 的URL路径


• 将要添加的狗发布到/ dogs / packs / p1。根据定义，POST会创建一个从属资源，这样就可以将狗添加到包中。


• 稍微翻新您的网址。在我看来你真的想要/ dogs / 1234，/ dogs / 1235等等，然后是/ packs / p1，/ packs / p2。然后你也可以简单地将< dog id =1> 发送到包中。

• use XML namespaces or other means of versioning (e.g. ?version=2) outside of the URL path
• POST the dog you want to add to /dogs/packs/p1. POST by definition creates a subordinate resource, so that would add the dog to the pack.
• Refurbish your URLs a bit. It seems to me you really want to have /dogs/1234, /dogs/1235 and so forth, and then /packs/p1, /packs/p2. Then you could also simply POST <dog id="1"> to the pack, too.

请记住，REST要求您正确识别资源。包不是狗的真正从属资源，每只狗应该有某种独特的标识符。然后，当访问/ packs / p1 / 1234时，您可能想要重定向到/ dogs / 1234。或者，您可能根本不会使该URL可用，尽管接受将下属资源POST到相应的包中。

Keep in mind that REST requires you to properly identify resources. packs are not really a subordinate resource to the dogs, and each dog should have some sort of unique identifier. Then, when accessing /packs/p1/1234, you would probably want to redirect to /dogs/1234. Or, alternatively, you would simply not make that URL available, despite accepting POSTing of subordinate resources to the respective pack.

我想的越多，就越有意义POST方法使。也许你甚至可以为所有狗提供/ pack / p1 / dogs /资源，与包装分开。然后，您可以将所有者信息等内容输入到/ pack / p1，通过/ packs / p1 / dogs /获取所有狗的列表（其中应包含 URL 的列表）包，例如/ packs / p1 / dogs / 1234，请参阅 HATEOAS ），添加一条新狗通过POST到/ packs / p1 / dogs /，并通过DELETEing / packs / p1 / dogs / 1235删除一只狗。每只狗可以是完整的代表，也许甚至可以重定向到/ dogs / 1234等，或者在这个背包中的狗的不同表现形式，但同样具有到完整狗的链接。取决于你想如何在一个包中代表一只狗，这当然也会影响你实际上发布到/ pack / p1 / dogs /的。满狗感觉不对，应该只是我上面显示的ID，可能还有关于与包的关系的其他数据。

The more I think about it, the more sense the POST approach makes. Maybe you could even have a /packs/p1/dogs/ resource for all the dogs, separate from the pack. Then, you can PUT stuff like owner information etc to /packs/p1, GET a list of all dogs via /packs/p1/dogs/ (which should contain a list of URLs to each dog in the pack, e.g. /packs/p1/dogs/1234, see HATEOAS), add a new dog to the pack by POSTing to /packs/p1/dogs/, and remove a dog by DELETEing /packs/p1/dogs/1235. Each dog could either be the full representation, maybe even with a redirect to /dogs/1234 etc, or a different representation of the dog in the context of this pack, but again with a link to the "full" dog. Depends on how you want to represent a single dog in a pack, and that will of course also influence what you actually POST to /packs/p1/dogs/. Full dog feels wrong, should really be just an ID as I showed above, maybe with additional data pertaining to the relationship with the pack.

这篇关于在REST API中使用PUT进行更新时，我是否应该允许发送完整的结构？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！