# Gateway Aggregation: One Request In, One Combined Reply Out

> A gateway calls several backend services for the app, then returns one merged response, so phones make fewer slow trips.

**In short:** Gateway aggregation has a gateway call several backend services for the app and return one merged response, so phones make fewer slow trips.

From "System design", a free course by Venkat R. Murty: https://designervenkat.online/learn/system-design/gateway-aggregation

## What you will learn

Many app screens need facts from several services at once. This lesson explains Gateway Aggregation, a pattern where one gateway takes a single request, asks several services for their parts, and returns one combined answer. You will see the problem it fixes, the steps the gateway follows, a worked example from a food delivery app, the ways it can fail, and the trade-offs that tell you when to use it and when to skip it.

- **Client:** The program that asks for data. Usually this is a phone app or a web page.
- **Gateway:** One entry point that sits between clients and the services behind it. Every request enters through it.
- **Endpoint:** One specific address where a service accepts requests, such as one web address for order tracking.
- **Backend service:** A program on a server that does one job, such as storing orders or finding drivers.
- **Microservice:** A small service that is built and run on its own, apart from the rest of the app.
- **Round trip:** One request sent over the network plus the reply that comes back.
- **Latency:** The delay between asking for something and getting the answer.
- **Chattiness:** A design where the client makes many small requests when a few larger ones would do.
- **Fan-out:** Sending one incoming request out to several services at the same time.
- **JSON:** A plain text format for structured data, written as named keys and values inside braces.
- **Payload:** The data inside a reply, such as a block of JSON text.
- **Parallel:** Running several jobs at the same time, rather than one after another.
- **Timeout:** A maximum time to wait for a reply before giving up on it.
- **Cache:** A stored copy of data kept close by so it can be reused without asking the source again.
- **Fallback:** A backup answer used when the main source fails, such as older saved data.
- **Partial failure:** When some of the calls in one operation work and others do not.

## What is the problem of too many trips to the server?

Imagine a home screen that shows data from six separate services. If the app asks each service on its own, it sends six requests and waits for six replies. Without aggregation, the client must call each service directly, which increases latency and complexity. The problem grows as the app adds features, because each new feature can add another call.

The Azure guidance on this pattern describes the same concern. Many round trips between the client and the backend services add network delay and make the app feel slow. In other words, the app pays for every trip, and the user feels the total.

### Why do phones feel this most?

A phone often runs on a weak or slow connection. The Azure pattern notes that sending individual requests over a cellular network with high latency is inefficient, and that it can lead to lost connections or incomplete replies. A laptop on office Wi-Fi may hide this problem. A phone on a train will not.

- **Slow waits:** Each separate call crosses the network and waits for its own reply. On a weak signal, those waits stack up, and the screen stays blank longer.
- **Battery drain:** Each request needs its own connection to send, wait on, and process. More connections means more work for the phone, which uses more battery.
- **Tight coupling:** Tight coupling means the app depends closely on how the backend is built. The app learns how the backend is split into services. If the team splits or merges services, the app code often has to change too.

## How does a gateway aggregate a request?

Aggregation moves the many calls from the phone to the gateway. In API aggregation, the client sends one request to the API gateway. The gateway routes requests to the services needed for the operation, then combines the results and sends them back. This reduces chattiness between the client and the application services. The steps below show the flow in order.

1. **Receive one request:** The client sends one call to a single gateway address. The gateway is a server that sits in front of the backend services.
2. **Fan out to services:** The gateway reads the request and decides which backend services it needs. It sends each of them a request of its own.
3. **Wait and collect:** The gateway waits for the replies. It does not wait forever. A gateway can use a timeout or a fallback so one slow service cannot hold up the reply forever.
4. **Merge into one shape:** The gateway places each service's data under a clear key in one object. The app then reads a single, predictable layout.
5. **Return one reply:** The gateway sends the merged data back as one response. The app makes one call and gets one answer.

### Why do parallel calls matter?

The gateway should send its calls at the same time. If the calls run one after another, the wait adds up, so the total time grows with every service. If the calls run together, the wait is roughly the time of the slowest single call. Fanning out concurrently means you pay roughly the cost of the slowest call.

$$
T = \max(t_1, t_2, t_3)
$$

In words: the total time T is the largest of the three call times, t1, t2, and t3. It is not their sum. The formula shows the best case, where all three calls start together and none of them waits for another. Gateway teams should check aggregation code for calls that run one after another by accident, because that is an easy mistake to make.

### Merging replies into one shape

Merging is more than gluing data together. The gateway chooses the shape the app needs, and it hides the internal names of each service. A screen might need the order status, the driver's area, and the restaurant's name. The gateway can place these under three plain keys, even though three different teams own the three services.

> **Tip:** Name the keys after what the screen shows, not after the service that supplied the data. The app then keeps working when a team renames or moves a service.

## Worked example: an order-tracking screen

Take a food delivery app. Its order-tracking screen shows three things: the order's status, where the driver is, and the restaurant's details. Those facts live in three services: an orders service, a dispatch service, and a catalog service. Without a gateway, the app would call all three. With a gateway, the app makes one call. The steps below follow that call from start to finish. The endpoint names are made up for this example.

1. **Client sends one request:** The app asks one gateway endpoint for tracking data, passing the order ID. The app does not know which services will answer.
2. **Gateway starts three calls:** The gateway sends a request to the orders service for the status, to the dispatch service for the driver location, and to the catalog service for the restaurant details. It sends all three at once.
3. **Services answer:** Each service returns its own part. The gateway waits for the replies, and it stops waiting if a timeout passes.
4. **Gateway merges the parts:** The gateway puts the three answers under the keys order, driver, and restaurant. The result is one payload.
5. **App draws the screen:** The app reads the single reply and draws the whole screen. Its code does not need to know that three services were involved.

The sample below imitates the gateway in Python. Each call to call_service stands in for a request to a backend service. The gather call starts all three at once and returns their results in the order they were listed. The asyncio.sleep(0) line only lets other tasks run. No network is used, so the output is always the same.

```python
import asyncio

async def call_service(reply):
    await asyncio.sleep(0)
    return reply

async def build_screen():
    order, driver, restaurant = await asyncio.gather(
        call_service({'status': 'on the way'}),
        call_service({'area': 'north side'}),
        call_service({'name': 'Green Bowl Cafe'}),
    )
    payload = {'order': order, 'driver': driver, 'restaurant': restaurant}
    print(payload)

asyncio.run(build_screen())

```

Output:

```text
{'order': {'status': 'on the way'}, 'driver': {'area': 'north side'}, 'restaurant': {'name': 'Green Bowl Cafe'}}

```

> **Tip:** Read the output as the one payload the app receives. The app made one request, and the gateway did the three lookups behind it.

## What happens when one backend fails?

Aggregation has a weak spot. One slow or broken service can spoil the whole reply. Sequential calls add up, while parallel calls overlap, so parallel calls are much faster. Still, a broken service can hurt the reply even when calls run in parallel. A good gateway must decide what to do when one of the calls fails. The Azure guidance warns that failures or slow responses in any one dependency can affect the final aggregated result.

### Three safety tools

Gateway designers use three simple tools for partial failure. They work together, and none of them needs to be complex.

- **Deadline per call:** Give each backend call its own time limit, called a timeout. Apply a timeout to each call, and return the data that arrived in time with a degraded flag, which is a marker saying the reply is incomplete. This is better than failing the whole screen.
- **Stand-in data:** When a service fails, the gateway can use a fallback. Stand-in data could be an older copy, a cached value, or a neutral default. The screen still loads, but the data may be old.
- **Partial reply with a flag:** Gateway aggregators should return the data that is available while clearly reporting which parts are missing. The app can then show the rest of the screen and a short note about the missing part.

Not every part of a screen matters equally. A gateway can decide, for each dependency, whether a failure is fatal or only degrades the reply. A missing payment status may need to stop the page, while missing reviews can simply be left out. The next sample shows a partial reply. The reviews service fails, and the gateway still returns the restaurant with a flag.

```python
import asyncio

async def call_service(reply):
    await asyncio.sleep(0)
    return reply

async def fail_service():
    await asyncio.sleep(0)
    raise RuntimeError('reviews service down')

async def build_screen():
    restaurant, reviews = await asyncio.gather(
        call_service({'name': 'Green Bowl Cafe'}),
        fail_service(),
        return_exceptions=True,
    )
    page = {'restaurant': restaurant, 'reviews': None, 'degraded': False}
    if isinstance(reviews, Exception):
        page['degraded'] = True
        page['note'] = 'reviews unavailable'
    else:
        page['reviews'] = reviews
    print(page)

asyncio.run(build_screen())

```

Output:

```text
{'restaurant': {'name': 'Green Bowl Cafe'}, 'reviews': None, 'degraded': True, 'note': 'reviews unavailable'}

```

## Trade-offs and when to use it

Aggregation is useful, but it is not free. The gateway takes on new jobs, and those jobs can fail or grow over time. Before you add aggregation, weigh the risks below against the speed it gives the app.

### Risks the gateway adds

- **Single point of failure:** A single point of failure is one part that, if it breaks, takes the whole system down. The gateway sits in front of every request, so design it carefully to meet the availability the app needs.
- **Extra hop and bottleneck:** The gateway adds one more step between the app and the services. Every request passes through it, so it can become a bottleneck, which is a narrow point where traffic slows down. Place the gateway near the backend services to keep the extra step short.
- **Business logic creep:** A gateway is easy to add rules to, so rules can pile up there. If aggregation needs custom business rules, complex data changes, or long multi-step workflows, put that work in a dedicated service behind the gateway.

> **Tip:** Keep the gateway thin. It should call services, wait, merge, and return. Pricing, discount rules, and other business decisions belong in services behind it.

### When another approach fits

Aggregation solves one problem: one screen needs many services. It is not the answer to every slow call. Instead of building aggregation into the gateway, you can place an aggregation service behind the gateway. That keeps the gateway light and lets the aggregation code scale on its own.

Skip the pattern when the problem is one service being called too often. If a client asks the same service for many items one by one, adding a gateway will not help much. A batch operation, which takes many IDs in one call, is often the better fix. The Azure guidance also suggests a batch operation may suit better when the goal is fewer calls to a single service. The pattern also matters less when the app sits close to its services and latency is low.

## Check your understanding

Try these two short scenarios. Each one needs the ideas above, not just a memory of the text.

**Quick check:** A mobile app's home screen makes six separate calls to six services. Users on weak connections see slow loads. One of the six services is sometimes down. What should you change, and how should the design behave when that one service fails?

A. Keep the six calls and cache the whole screen on the phone for a day.
B. Put the six calls behind one gateway endpoint that runs them in parallel, sets a timeout for each, and returns the other five with a flag when the sixth fails.
C. Make the app retry the failing service until it answers, then show the full screen.
D. Fail the whole home screen with one error whenever any single service fails.

**Answer:** B. One gateway call cuts the trips over the weak connection. Parallel calls keep the wait short, and per-call timeouts with a flag keep the rest of the screen working when one service is down.

**Quick check:** A team wants the gateway to apply a discount rule, so the app shows a final price. The rule needs its own calculations and may change often. What is the best design?

A. Write the discount rule inside the gateway, since the gateway already sees every reply.
B. Let the app calculate the discount itself, since the app is closest to the user.
C. Put the discount rule in its own service behind the gateway, and let the gateway call it and merge the result.
D. Store a copy of every price in the gateway's memory and skip the discount step.

**Answer:** C. Aggregation should combine replies, not hold business rules. A separate service keeps the gateway thin and lets the rule change without touching the gateway or the app.

## Key takeaways

- **One call in:** The client makes one request to the gateway, and the gateway makes the many backend calls. This cuts round trips, which helps most on slow mobile networks.
- **Parallel fan-out:** The gateway should call its services at the same time and merge the results into one clear shape. Plan for timeouts and partial replies, because one failing service should not sink the whole screen.
- **Thin gateway:** Keep business rules in services, not in the gateway. Watch for the gateway becoming a single point of failure or a bottleneck, and use a different approach when the real problem is elsewhere.

## Sources

- [Azure Architecture Center: Gateway Aggregation pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/gateway-aggregation)
- [Azure Architecture Center: Use API gateways in microservices](https://learn.microsoft.com/en-us/azure/architecture/microservices/design/gateway)
- [Azure Architecture Center: Design patterns for microservices](https://learn.microsoft.com/en-us/azure/architecture/microservices/design/patterns)
- [Microsoft Azure blog: Design patterns for microservices](https://azure.microsoft.com/en-us/blog/design-patterns-for-microservices/)
- [Aggregator Pattern (commons-os)](https://commons-os.github.io/patterns/aggregator-pattern/)
- [KloudVin: API Gateway and Backend-for-Frontend Patterns: Aggregation, Composition, and Versioning](https://kloudvin.com/article/api-gateway-bff-pattern-aggregation-architecture/)
- [API7.ai: How to Implement API Aggregation in API Gateways](https://api7.ai/learning-center/api-gateway-guide/api-gateway-api-aggregation)
- [Developers Voice: Gateway Aggregation Pattern in .NET](https://developersvoice.com/blog/cloud-design-patterns/gateway-aggregation-pattern/)
- [CodeBegun: Microservices API Gateway Interview Questions](https://www.codebegun.com/interview/microservices/api-gateway)
- [Joud Wawad: The API Gateway Pattern: Design, Tradeoffs, and the Failure Modes](https://joudwawad.medium.com/api-gateway-pattern-in-microservices-when-and-how-62a0bf0ea93b)
