I'm working on API design for a mobile app where the user can send one or more photos that will be stored in the database.

Currently I have three routes, post photo/create which will send one photo every call and returns json object when successful, post photo/delete which will delete the photo by id and return empty object, and get /photos which will return array of objects.

However the mobile programmer (Android) thinks this is slow and is a bad practice, also the return is inconsistent, and asks for a single API POST route that he can use to send multiple photos.

How should I design the API?

Batch operations can be quite useful: a single request tends to be faster than making multiple requests one after another. In particular, the speed of a request is limited by the internet connection throughput and latency (waiting time). Batch requests help with both, but mostly eliminate per-request latency because you only have to wait for a single response.

There are some big problems with batch requests, though: you now have to consider cases where some but not all of the individual requests succeed. And you may not be able to use the URL for routing, if the batch request can contain individual requests for API endpoints.

So what ends up happening is that you either re-invent your own RPC and transport protocol, or have to use an existing protocol like SOAP or GraphQL. This is not necessarily bad, this is just a completely different API style from what you are used from HTTP. In an extreme case, all API requests are wrapped as POST requests to the same URL, and the real actions are determined by a JSON or XML document in the request body.

Most web frameworks do not anticipate such APIs and can't help you building it.

But all of this might be unnecessary. Your app developer can already send multiple requests in parallel (won't help with throughput but also gets rid of some latency). Modern HTTP standards also reduce the latency. HTTP/1.1 connections can be reused for multiple requests, and HTTP/2 connections can multiplex multiple requests over the same connection.

With HTTP/2 there is no point in offering batch APIs because individual requests are just as efficient, without having to use a different protocol. For similar reasons, HTTP/2 also makes it unnecessary to combine small icons into a larger “sprite” image when designing a website.

Your Answer

 
discard

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.