Exploring composite APIs

Introduction

Have you heard of composite APIs? Do you know what it does? Like most of the freshers out there, even I had no idea about such architecture. I recently joined a company as a product manager, and my area of work includes managing the development of the company’s composite API. To help you better understand what a composite API is, read along with this scenario:

Assume that you are developing the backend for a food delivery service. A general flow for ordering food for a signed-in user looks like this:

Architecture without using composite API

1. The user selects the restaurant they want to order food from, and the UI fetches the list of items available for that restaurant and their respective prices.
2. The user selects the food item(s) from the displayed list, which is then added to the user’s cart.
3. To calculate the total amount of items in the cart, the UI makes specific calls to the backend. These calls involve
   - Applying discounts or rebates due to the user’s existing subscription(s)
   - Calculation of taxes on the deliverables
   - Checking for price fluctuations of the items in the cart
   - Charges based on high-demand surges
   - Calculation of delivery charges using Maps and Trafic API.
   - Factoring extreme weather conditions using some Weather API to increase the charges or disallow the user to place the order altogether.

4. The user is then taken to the checkout page and eventually to the payment gateway for making the transaction.

Well, for JavaScript developers, this is a callback hell. You will have to wait for each API call to respond before invoking the next one so that you can pass on the data of the previous call to the next one. Damn those poor devices with entry-level specs handling all that business logic.

Hello, wait a second. Did you also notice how many ways this can fail? If API A isn’t working, B won’t work. If C isn’t working, D won’t. It’s a freaking domino effect. Imagine how much focus handling all these exceptions will require. Now, now. Don’t be an idiot. You can’t use try-catch here if you want to make a robust system. It's much more than "If it works, it works, or else show them the error page." Suppose the expected time to deliver the product can't be displayed because of weather API failure. In that case, you can't deny the customers to make an order because of an "Internal Error" message. Say goodbye to your revenue.

I am sluggish when I am working with the front end. Matching the UI from the designs from Figma, applying UI validations, and handling edge cases is already too much. I just want to consume data from an API and render the UI according to that. But in this case, it is a nightmare. It would be much easier to get data in a single API call using composite APIs. I can focus more on building UI than handling data. The following diagram depicts how composite APIs work.

Architecture after using composite API

What is a composite API?

Usually, a backend provides micro-level control to the entire system, and it is often the case when there is a need for data from multiple sources in the system. This is where the composite API comes into play. Developers working on composite APIs are not creating new resources. They are consuming existing endpoints to organize the data in a format required by the UI. In other words, they batch multiple API calls into one by handling business logic.

In fact, composite APIs are built over the existing architecture of the product and are usually introduced later over the product’s lifetime. Your organization might have been using traditional APIs for fetching data for years before realizing the need for a composite API. Your product should work just fine even without it.

Why do we need composite API?

Every other developer is tempted to use new technology in their existing project. But just like blockchain is not the solution to every product, the composite API has only specific use cases. A composite resource is used when:

• A series of API requests must be made to obtain the final data.
• There are multiple CRUD operations taking place.
• Output of one request is the input of the subsequent request
• When there is a microservice architecture, data must be fetched from different services simultaneously.

Benefits of using a composite API

• On platforms where the number of API calls you make is counted and limited, a call to a composite API is counted as a single API call.
• Although the composite API makes the same number of calls as the traditional model, the load on the frontend is relatively low as the composite platform makes all the main calls.
• It keeps the frontend code clean because failure logic is handled by the composite platform and does not need to be developed on the frontend. Suppose any API fails, and the entire batch process can’t be completed successfully. In that case, the composite platform will handle the logic, and the frontend needs to address the screen rendering accordingly.
• It can reduce server load and improve application performance.

When to (and not to) use a Composite API?

Composite API is a fantastic solution to handle the complexity of fetching data from the frontend, but it is not the answer to every problem. Use this architecture when sequential calls to various services for data fetching are needed. If it is just an update job, use a Batch API I have seen people requesting for endpoints to be made in composite API just for making one freaking call. People, it is not a proxy! Your architecture should not change the state of the backend directly. It instructs the existing APIs to update the state. Don’t expect your Composite API to be an alternative to the original backend. The architecture can introduce an architecture-level storage solution to store temporary data. It can also cache data for fast reads.

Closing notes

There are very few resources available on the internet that talk about Composite APIs. However, resources by Salesforce are good enough to know what it is and how you can create a composite API using their platform. It also lays down a guide for developing a Composite API architecture. It is the company’s decision on how they want to structure it. The response pattern shown on the Salesforce docs is very different from what my company uses, and it must be the same for all various other organizations using this architecture. And that’s the beauty of software development. There is no hard and fast rule to doing something. You can be imaginative.