I’m working on a REST API where I need to handle both single operations and batch processing for the same functionality. Let’s call this operation ‘Task’.
Currently I have this endpoint for single operations:
/resource/:resourceId/task/:taskId
Now I need to add batch processing capabilities and I’m considering these two options:
Option 1: Create separate endpoints
Keep /resource/:resourceId/task/:taskId for single operations
Add /resource/:resourceId/task with task IDs array in request body for batch
Option 2: Use query parameter approach
Modify to /resource/:resourceId/task/?batch=true/false
When batch=true, expect taskIds[] in request body
When batch=false, expect single taskId in request body
I’m leaning towards the first approach but wanted to get some feedback from the community. Has anyone dealt with similar API design decisions? What are the pros and cons of each approach?
Any suggestions or alternative solutions would be really helpful. Thanks!
option 2’s way too complicated for this. go with option 1, but make sure your batch endpoint handles partial failures well - return individual status for each task. also, set up different rate limits for batch vs single operations since batches eat more resources.
I faced a similar dilemma while designing a document processing API a couple of years back. After testing both options in a production environment, I recommend going with Option 1 but with a slight adjustment. Use /resource/:resourceId/task/:taskId for single operations and change the batch endpoint to /resource/:resourceId/tasks. This clearer naming convention indicates batch processing right away. The query parameter approach could lead to confusion for developers, as conditional logic can make your API inconsistent and documentation more complex. We tried that method first and spent considerable time clarifying request formats with frontend teams. A useful tip: ensure that your batch endpoint returns responses in the same order as the input array, even if some operations fail, as we learned this the hard way and it caused confusion regarding the success of tasks.
I’ve built similar functionality for an inventory system, and I’d go with Option 1 hands down. Separate endpoints just make way more sense - your API becomes way more predictable and clear for anyone using it. But here’s what I learned the hard way: keep your response formats consistent. Your batch endpoint should always return a collection (even for single items), and your individual endpoint should always return a single object. Trust me, mixed response structures will confuse the hell out of your clients. Also, definitely add idempotency keys for batch operations - they get retried way more often than individual calls. Oh, and plan your monitoring early. We got caught off guard because batch operations need completely different metrics tracking than individual calls.