RESTful 资源 - 接受对象列表 [英] RESTful resource - accepts a list of objects

问题描述

我正在构建一组 RESTful 资源，其工作方式如下:(我将使用people"作为示例):

<前>获取/people/{key}- 返回一个人对象 (JSON)

<前>GET/people?first_name=鲍勃- 返回first_name"为Bob"的人员对象列表(JSON)

<前>PUT/人/{key}- 期望有效负载 (JSON) 中的人对象，更新人具有在 URL 参数中找到的 {key} 以匹配有效负载的数据存储.如果是新对象，则客户端指定新对象的键.

到目前为止，我对设计感到很满意(尽管欢迎提出任何意见/批评).

我还希望能够列出人员列表，但是我对我的设计的 REST 性没有信心.这就是我的想法:

<前>PUT/人- 期望 JSON 形式的对象列表，其中包含对象中的键(键":32948").更新数据存储中的所有相应对象.

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

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

PATCH"听起来很棒，但我不想使用它，因为它还没有被广泛使用，并且还与许多程序和 API 不兼容.

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

大家有什么意见/建议吗?

跟进:::

虽然我对使用 POST 犹豫不决，因为它似乎是最不常见的分母，对于 RESTful 操作来说是包罗万象的，并且关于这个操作可以说更多(特别是它是幂等的)，但不能使用 PUT 因为它的要求太窄了.具体来说:资源没有被完全重写，并且等效的资源没有从 GET 请求发送回相同的资源.当应用程序、API 和/或程序员尝试使用资源并遇到资源的意外行为时，使用具有超出其规范的属性的 PUT 可能会导致问题.

除了已接受的答案之外，如果操作绝对必须是 PUT 并且将 UUID 附加到资源路径的末尾，则 Darrel Miller 提出了一个很好的建议，以便等效的 GET 请求将返回等效的资源.

解决方案

POST 表示除 GET、PUT 和DELETE(通用哈希表操作).由于通用哈希表操作不合适，请使用 POST.POST 的语义由实体被POST 处理到的资源决定.这与众所周知的通用哈希表方法的语义不同.

POST/people/add-many HTTP/1.1主机:example.com内容类型:应用程序/json[{姓名":鲍勃"}，{姓名":罗伯特"}]

I'm building a collection of RESTful resources that work like the following: (I'll use "people" as an example):

    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.

I feel pretty comfortable with the design so far (although any input/criticism is welcome).

I'd also like to be able to PUT a list of people, however I'm not confident in the RESTfulness of my design. This is what I have in mind:

    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.

This operation will be idempotent, so I'd like to use "PUT". However its breaking a rule because a GET request to this same resource will not return the equivalent of what the client just PUT, but would rather return all "people" objects (since there would be no filters on the query). I suspect there are also a few other rules that might be being broken here.

Someone mentioned the use of a "PATCH" request in an earlier question that I had: REST resource with a List property

"PATCH" sounds fantastic, but I don't want to use it because its not in wide use yet and is not compatible with a lot of programs and APIs yet.

I'd prefer not to use POST because POST implies that the request is not idempotent.

Does anyone have any comments / suggestions?

Follow-up:::

While I hesitated to use POST because it seems to be the least-common-denominator, catch-all for RESTful operations and more can be said about this operation (specifically that it is idempotent), PUT cannot be used because its requirements are too narrow. Specifically: the resource is not being completely re-written and the equivalent resource is not being sent back from a GET request to the same resource. Using a PUT with properties outside of it's specifications can cause problems when applications, api's, and/or programmers attempt to work with the resource and are met with unexpected behavior from the resource.

In addition to the accepted answer, Darrel Miller had an excellent suggestion if the operation absolutely had to be a PUT and that was to append a UUID onto the end of the resource path so an equivalent GET request will return the equivalent resource.

解决方案

POST indicates a generic action other than GET, PUT, and DELETE (the generic hashtable actions). Because the generic hashtable actions are inappropriate, use POST. The semantics of POST are determined by the resource to which an entity is POSTed. This is unlike the semantics of the generic hashtable methods, which are well-known.

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

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

这篇关于RESTful 资源 - 接受对象列表的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！