Search code examples
api-design

What is the expected logic of a batched POST request to a subresource

I like the idea of vectorized/batched requests similar to what the StackExchange API offers and would like to implement something for my own API, i.e. GET /users/1;2;3;4;5 would return the selected user resources with id 1 to 5.

I think this is fairly simple when reading data, but what would be the expected behavior for i.e. a POST request to a subresource?

POST /1;2;3;4;5/subresource

Would this mean:

  • Creation of five new subresources, assigned to each id (1:1)
  • Creation of a single new subresource, but assigned to each resource id (1:n)
Solution

  • I have a couple of concerns regarding this approach. First, resources should be uniquely addressable via certain resource locators (URIs). Using your approach however bypasses this requirement in some way IMO. This approach may also lead to other issues later on, i.e. plenty of frameworks do not allow URIs that exceed a certain character size.

    Furthermore, instead of consecutive resource IDs the resource should use UUIDs instead. This will first and foremost prevent guessing attacks and also prevent logical issues on moving resources or inserting some in between.

    The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics.

    In regards to HTTP POST operations, the specification clearly states that the semantics of any body received via POST is up to the service developer. So you are basically allowed to do anything within a POST request. As the semantics is totally up to you, you have to document the behavior explicitely. Not documenting the applied logic will leave a large grey-zone for service users.