I am designing an API and I want to allow the clients to be able to create several resources at once. A client can POST an Order that has several Items.
One approach would be to allow the client give unique ids at the Order level and for each of the items levels, and me storing those (as well as our internal ones), but that would allow the client to request based on its ids. Example of request:
{
order_ref: 'XXX',
items: [
{ item_ref: 'xx', quantity: 5 },
{ item_ref: 'yy', quantity: 5 },
]
}
The other approach is to return an id for the order and for each of the items, but that seems not escalable as an order can have a lot of items so the request could even timeout. It would also mean that the return would need to be in order so they can match the returned ids with what they requested.
What is the approach that one should be taking?
If you take your first approach, clients must create ids. Sometimes this is ok, but usually it's annoying for them. Unless the id is an intrinsic part of the thing that won't ever change, they're just going to have to come up with their own random id and store it in their own local database. If your clients want to be able to do this, this is the right approach. You should enforce uniqueness across their generated ids by resource type, and just use those in your database.
Otherwise, the second approach is preferable because annoying your clients is bad for business. Yes, it's going to scale poorly if they add a thousand new items, but the response won't be that much larger than the request, since you're just adding 'id' properties in the response.