CODEWITHSUNDEEP
resthttp-method
mcmurphy
mcmurphy

Reputation: 805

Correct (RESTful) HTTP Method for handing mixed / batch requests

I have an application that needs to send multiple (change) requests to the server at a time. These requests are being sent in a batch, represented by a JSON object. The requests can be of any (change) type (e.g. creations, updates, deletions).

the JSON looks something like this:

[
  { "delete": { "id": "to delete" } },
  { "update": { "id": "to update", "data": {} } },
  { "create": { "data": {} } },
  ...
]

My question is simple:

If I was sending these over to the server one at a time, I'd use DELETE, PUT or POST depending on the nature of the operation, but since I'm sending over a batch potentially containing all three types of requests, I'm not sure which method is most appropriate (aside from DELETE).

Which is the correct HTTP Method to use in this instance?

Thanks.

Upvotes: 1

Views: 2841

Answers (3)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57239

If I was sending these over to the server one at a time, I'd use DELETE, PUT or POST depending on the nature of the operation, but since I'm sending over a batch potentially containing all three types of requests, I'm not sure which method is most appropriate (aside from DELETE).

Which is the correct HTTP Method to use in this instance?

"It depends".

The key point is this: http semantics apply to resources, which live in the integration domain. The fact that these representations you are sending impact the domain model in interesting ways isn't relevant.

The method you choose should have unsafe semantics, since you are encouraging the origin server to change. You also need a method where the message body is meaningful. Of the methods defined within the HTTP spec, you have PUT and POST -- either of these is fine. PATCH may also be suitable, depending on whether or not you can make this collection of changes atomically.

Example: suppose what we are really doing is taking the body of the message, and sticking it into a queue to be handled "later". The REST part is taking that implementation, and dressing it up with an HTTP disguise.

Either PUT or POST is perfectly fine for that. Using POST to add something to a queue should not be a big surprise. PUT is analogous to inserting the message into a key value store.

HTTP is an application protocol whose application domain is "the transfer of documents over a network." -- Jim Webber

What you have at your client is a document, which happens to describe changes that you want to make in your domain model. You are using HTTP to transmit a copy of that document to the server. Does POST work for that? Yes. Does PUT work for that? also yes.

Consider this resource, which means exactly what it says on the tin

/newest-message-in-queue

Can you update that resource by sending a new representation via POST? Sure. Can you update that resource by sending a PUT? Of course. Will the side effects on the domain objects work either way? Yes.

Can the client tell the difference between this, and changing a value in a key value store? No <-- and that's the point; we're disguising our implementation behind a generic document store semantics, so that we can take advantage of off-the-shelf-ware.

Upvotes: 1

Rafael
Rafael

Reputation: 7746

The correct method to use is a POST method since you are creating a batch-process resource. In addition, you should respond with a 202 Accepted status code which indicates "The request has been accepted for processing, but the processing has not been completed." (RFC 2616)

I hope this helps!

UPDATE:

This should definitely be a POST method because this request IS NOT idempotent. Before you continue, please see What is idempotency in HTTP methods? and Is REST DELETE really idempotent?.

If this request is made multiple times, it may have n number of side-effects (because it creates resources)!

I retracted my PUT recommendation comment because I misspoke—PUT should be idempotent.

Upvotes: 2

joker
joker

Reputation: 3742

Well, AFAIK, there is no such method to do so. You can use just the json as in your post with a new POST request.

This new request will parse the data sent and call delete method on delete related data, put on put related data, and so on.

Upvotes: 1

Related Questions