CODEWITHSUNDEEP
restapipostapi-design
AKH
AKH

Reputation: 277

Restful Design - Parent collection object in response when POSTing a resource

Let's say we have a collection resource called shelf (of book resources) and we would like to POST a new book: 

[POST] /shelves/{shelf-id}/books  [request body -- a book]

I know that the response should be either empty with a reference to the newly created resource (201) or include the created resource (200).

Let's say the clients that are creating book resources, will need to show summary of the shelf the new book is added to. One solution should be making clients to first do a POST (let's call it Req#1 -- to create the new book), and then a GET (Req#2) on the shelf resource to get the summary.

What if we care a lot about efficiency and want to return the result of Req#2 implicitly when getting Req#1 on the server and save one request on the client side? Is it OK based on REST principles to return the parent collection resource information in the response when a resource is added to the collection?

Any alternative design?

Upvotes: 1

Views: 353

Answers (2)

Chris Broski
Chris Broski

Reputation: 2550

I know that the response should be either empty with a reference to the newly created resource (201) or include the created resource (200).

This isn't true. According to the spec:

The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field. The response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. The origin server MUST create the resource before returning the 201 status code.

In summary, use a 201 status response with information about the new resource. Please don't mix information about other resources with it. That is not RESTful, and apart from pedantry, it probably will make a messy API for very little benefit.

Upvotes: 0

Evert
Evert

Reputation: 99728

It's 'OK' for REST design to return different resource states, but HTTP doesn't have a standard way to do this. If you uses the HAL format for you REST api, it does have a way to do embedding, so I suppose you could embed different resources to the response of a POST request.

Note that there's no standard I know of that suggests that the following statement is true: I know that the response should be either empty with a reference to the newly created resource (201) or include the created resource (200).

Anyway, what are you trying to solve? Is it really that expensive to do an extra HTTP request? Where do you base that concern on? What's expensive about it? Is it the latency of having to do an extra roundtrip?

If that's the case, you could consider using HTTP/2 push to push a new version of your parent resource. It's probably the most standards compliant way. If your server and client support this well, then this also means you can use this as a great standard mechanism to push things to clients because they might soon request it.

Upvotes: 1

Related Questions