Many asynchronous calls vs single call to the API

Question

We are developing a REST API which among others is going to be consumed by an HTML5 frontend via javascript. The application is for use within the organization and usually has about 300 users, but we want to scale well up to 1000 users or so.

Normally connections to the API will be made within the LAN so the quality and latency of the connection will be good, although it is not excluded occasional use over the Internet where connections could be slower and with more lag via 3G/4G.

The two options that we thought are:

1. The frontend will make several simultaneous asynchronous calls to the API to load the various components of the interface.

   • Pros: Simplicity.
   • Cons: More connections to the server.

2. The controller of the frontend will make a single call to the API passing as parameters which objects need to be fetched.

   • Pros: Only one connection to the server, although the server will make several connection to the database.
   • Cons: Requires mechanisms in both frontend and API. It complicates the design.

Further explanations: There will be different resources .../Product .../Locations etc. These resources could be fetched alone, but there will be another abstract resource .../screen?Product&Locations that will fetch both in one call.

Answer 1

Option 1 (multiple async calls) is the best choice because:

1. each individual call is its own entity, so you can retry individually if something happens to fail. In the monolithic 'one-call' architecture, if one thing fails you have to do the entire call again
2. the server side code will be simpler: again, modularity, meaning that different developers can work on different API resources
3. In a typical MVC pattern it doesn't make sense to have one API call load multiple separate resources; for example, if you make a request to /products to get a list of products to show on a page, and you also want to display a list of locations where popular products are sold, you have two separate resources: Product and Location. Though they are displayed on the same page, you can't logically make a call to /products and have it also return locations as well
4. your logging/utilization reports will be simpler in the modular approach. If you make a request to /products and you're also loading locations, your log files are going to be really confusing
5. if you have a problem with a particular resource, the one-call approach will cause the entire page to break and it won't be obvious to your users what broke - and this means it will take longer for your team to fix the issue; however, in the modular approach if one thing breaks, it will be very obvious what broke and you can fix it faster. It also won't ruin the rest of the page (unless things are too closely coupled...)
6. it will be easier to make changes in general if things are separated; if you have 5 resources being loaded by one API call, it will be harder to figure out how to not break things when you want to change something

The whole point is that resources are separate, and in a REST API returning many separate resources from a single API path doesn't make sense, even if you're "saving connections to the server". By the way, using parameters to conditionally load (different) resources is not RESTful.

All that said, the only logical option is to make multiple async requests to separate resources: take the modular approach!

PS - Don't prematurely optimize away "connections to the server", especially when HTTP connections are incredibly low overhead and you're on a LAN. That kind of thinking instead of choosing the simpler design right off the bat is going to get you into trouble later.