8

Thinking in a RESTful way, is it correct to use POST to create in a single call a resource and its sub-resource? In my application I have the resource /notices/{notice} and sub-resource /notices/{notice}/photos/{photo}. A {photo} can't exists without a {notice}, but a {notice} doesn't have necessarily photos. Normally, I have to do first a POST to create a notice, then another POST to add a photo.

Now I want to allow the creation of a notice with a photo directly attached, enabling the creation of /notices/{notice} and /notices/{notice}/photos/{photo} with a single POST request to /notices/{notice}/photos/{photo}, with a multipart content describing both the resources (JSON for notice, binary for the photo). I think I will return the Location header only for the sub-resource.

Essentially, I want this to prevent Android clients to send two POST request to the server to upload a notice with a photo. Is this correct? Or does it infringe REST principles? Should I consider to keep them separate and make two different requests? Or is it wrong to consider photos a separate entity from the notice? Should I keep only /notices/{notice} as resource, using PUT to add photos?

Which is the best solution?

TheWhiteRabbit
  • 15,480
  • 4
  • 33
  • 57
user1781028
  • 1,478
  • 4
  • 22
  • 45

2 Answers2

5

Yes, there is nothing wrong with creating sub-resources at the same time you create the parent resource. It would even be OK to use PUT instead of POST to do this, as everything under the parent URL is part of/belongs to the resource you are uploading.

EDIT:

Now I want to allow the creation of a notice with a photo directly attached, enabling the creation of /notices/{notice} and /notices/{notice}/photos/{photo} with a single POST request to /notices/{notice}/photos/{photo}

This I disagree with. I suggest POSTing to the collection resource's URL, /notices. You provide the notice and its photos as a single representation (request body). The back end will then create resources for both the notice and any constituent photographs.

Nicholas Shanks
  • 10,623
  • 4
  • 56
  • 80
  • Surely by that logic, everything after the endpoint would be a modification of the root resource and therefore make the idea of `POST` redundant? (I may have misunderstood you?) – James Jan 11 '13 at 11:42
  • Theoretically, yes. You can think of /questions as a sub resource of stackoverflow.com. This however does not make POST redundant. – Nicholas Shanks Jan 11 '13 at 11:44
  • I would argue that the use of `POST` would be the only sensible option here as the OP isn't modifying the top most resource (directly)? To create the resource with a `PUT` would imply that this sub-resource already exists? – James Jan 11 '13 at 11:48
  • I don't believe so. Think of an API where a resource has several fields, and one of them is a big data blob. It might be the case that some clients don't want this, so the API author creates 3 URIs: `/resource`, `/resource?blob=false` and `/resource/blob` to send the whole resource, the resource without the large data item, and the data alone. In this case, a PUT to /resource containing all of the resource would also make stale the other two URIs (a conditional GET/HEAD would not return 304). – Nicholas Shanks Jan 11 '13 at 11:57
  • @James: Seems there is not already a chat room for REST so I created one: http://chat.stackoverflow.com/rooms/22578/restful-chat Pop in and we can discuss. I am interested in your opinions. – Nicholas Shanks Jan 11 '13 at 12:15
  • how client handles in case of failure ? or how server will intimate individual HTTP response code or Resource state ? – TheWhiteRabbit Jan 11 '13 at 12:27
1

Although its essential in many cases, multiple edits/creates are not formally addressed by the RESTful architecture style.

Problem starts when you need to report failures on part of the collection, and the problem is worsen when they failures have different cause.

An it will effect choosing the right Hypermedia controls which are essential for the client to find a way forward in the given transaction/conversation.

so my suggestion is to have a nested cycle or POST requests rather than a sing POST to create nested Resources , so that it'd be easier and clearer to address each Resource state change.

TheWhiteRabbit
  • 15,480
  • 4
  • 33
  • 57
  • The solution to this is to fail on the first error and rollback the server state. Whether implementing transactions in this way is worth the effort depends on how busy your server is. – Nicholas Shanks Jan 11 '13 at 11:48
  • Please drop in to http://chat.stackoverflow.com/rooms/22578/restful-chat and discuss this. I would like to hear more on what you have to say. – Nicholas Shanks Jan 11 '13 at 12:16