2

I'm working on building a REST API and I'm not too sure what the correct way is to represent an endpoint that generates data. Assuming the ressource is about "items", I have the usual endpoints:

  • GET /items => list items
  • POST /items => create a new item
  • GET /items/{id} => get an existing item
  • PUT /items/{id} => update an existing item
  • DELETE /items/{id} => delete an existing item

Now, I also have a process that can generate items based on some parameters or configuration in the system. What is the correct way to define this endpoint with REST?

I am tempted to use also POST /items but this one is already taken to create a "single" new item. Is is correct to sometimes use:

  1. POST /items?from=2020-07-15&to=2020-07-21 for with no body => this creates a list of items
  2. POST /items with an item in the body => this creates a single item

Thanks for your input!

mxdev88
  • 23
  • 4
  • Does this answer your question? [REST API - Bulk Create or Update in single request](https://stackoverflow.com/questions/28596688/rest-api-bulk-create-or-update-in-single-request) – dbaltor Jul 15 '20 at 21:46
  • thanks for the suggestion @dbaltor. My questions was more oriented on whether it was "correct" REST-wise to have the same endpoint behave differently based on payload or query params. – mxdev88 Jul 16 '20 at 08:51
  • Welcome. I believe POST is the only way to go as your request is not going to be idempotent. However, the HTTP verb and URI are not the only thing to consider. The processing (atomic or not, sync or async) and the respective response with the proper code (200, 202 or 400) are paramount as well. That's why I refer you to the link to a comprehensive response. – dbaltor Jul 16 '20 at 14:46

2 Answers2

2

It is perfectly acceptable in REST to overload POST.

You might image on the web having two different forms, that promise to do different things, that share the same action uri. Browsers will do exactly the right thing - taking the input fields of the form, composing the body of the request, and then sending the resulting POST request using the same target-uri.

So long as the server can distinguish between the two meanings using the payload, there is no difficulty.

POST is, in general, the right answer any time you are doing anything other than remote authoring. See Fielding 2009: It is okay to use POST.

From the perspective of the client, the target-uri doesn't matter much, so if you want to create a different resource to handle the bulk creation use cases, that's OK too. The main reason that we might care about using

POST /items

is that doing so successfully will automatically invalidate the previously cached representations obtained via

GET /items
Community
  • 1
  • 1
VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
  • I quite like the overload solution. I should probably document better my endpoint to state that `POST /items` accepts a list of items as well as optionally query params that will generate the list of items. thanks – mxdev88 Jul 16 '20 at 08:43
1

That would definitely be a POST. You can have POST /item with and item body and then have something like POST /item/batch?param=1&param=2 to mass-generate items based on the parameters you're passing.

Philip
  • 319
  • 5
  • 13