Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

RESTful resource - accepts a list of objects

Tags:

rest

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.

like image 432
Chris Dutrow Avatar asked Jul 07 '10 21:07

Chris Dutrow


People also ask

What is a resource in RESTful API?

The fundamental concept in any RESTful API is the resource. A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it.

What is resource model in API?

A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.” - Roy Fielding's dissertation. Resources form the nucleus of any REST API design.


1 Answers

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" }
]
like image 77
yfeldblum Avatar answered Nov 10 '22 20:11

yfeldblum