RESTful资源 - 接受对象列表

Question

我正在构建一个RESTful资源集合,其工作方式如下:(我将以"people"为例):

    GET /people/{key}
      - returns a person object (JSON)

    GET /people?first_name=Bob
      - returns a list of person objects who's "first_name" is "Bob" (JSON)

    PUT /people/{key}
      - expects a person object in the payload (JSON), updates the person in the 
        datastore with the {key} found in the URL parameter to match the payload.
        If it is a new object, the client specifies the key of the new object.

到目前为止,我对设计感到非常满意(尽管欢迎任何投入/批评).

我也希望能够列出一个人的列表,但是我对我的设计的RESTful性并不自信.这就是我的想法:

    PUT /people
      - expects a list of objects in JSON form with keys included in the object
        ("key":"32948").  Updates all of the corresponding objects in the datastore.

这个操作是幂等的,所以我想使用"PUT".但是它违反了规则,因为对同一资源的GET请求不会返回客户端只是PUT的等价物,而是返回所有"人"对象(因为查询中没有过滤器).我怀疑还有一些其他规则可能会被打破.

有人提到在我之前的问题中使用"PATCH"请求:具有List属性的REST资源

"PATCH"听起来很棒,但我不想使用它,因为它尚未广泛使用,并且与许多程序和API不兼容.

我不想使用POST,因为POST意味着请求不是幂等的.

有没有人有任何意见/建议？

跟进:::

虽然我犹豫是否使用POST,因为它似乎是最不常见的分母,RESTful操作的全部内容以及关于此操作的更多内容(特别是它是幂等的),PUT因为其要求太窄而无法使用.具体来说:资源未完全重写,并且等效资源未从GET请求发送回同一资源.当应用程序,API和/或程序员尝试使用资源并且遇到来自资源的意外行为时,使用具有其规范之外的属性的PUT可能会导致问题.

除了接受的答案之外,Darrel Miller有一个很好的建议,如果操作绝对必须是PUT,那就是将UUID附加到资源路径的末尾,这样等效的GET请求将返回等效资源.

Answer 1

POST表示除GET和PUT,和DELETE(通用散列表操作)之外的通用操作.由于通用散列表操作不合适,请使用POST.语义POST由实体所POST编辑的资源确定.这与通用散列表方法的语义不同,后者是众所周知的.

POST /people/add-many HTTP/1.1
Host: example.com
Content-Type: application/json

[
  { "name": "Bob" },
  { "name": "Robert" }
]

Answer 2

在这种情况下，使用 PUT 绝对是错误的动词。POST 旨在完全按照您的要求进行操作。从HTTP 规范：

POST 和 PUT 请求的根本区别体现在 Request-URI 的不同含义上。POST 请求中的 URI 标识将处理封闭实体的资源。该资源可能是一个数据接受过程、一个通往其他协议的网关，或者是一个接受注释的单独实体。相比之下，PUT 请求中的 URI 标识了包含在请求中的实体——用户代理知道 URI 的意图，并且服务器不得尝试将请求应用于某些其他资源......

因此，如果您想在一次调用中更新多个资源，则必须使用 POST。

只是因为 PUT 需要是幂等的而 POST 不是，并不意味着 POST 不能是幂等的。您对 HTTP 动词的选择不应基于此，而应基于请求的资源和所操作的资源之间的关系。如果您的应用程序直接处理请求的资源，请使用 PUT。如果它作用于其他资源（或资源，如您的情况），请使用 POST。