How do you call an on-premise API from a cloud application?

Four patterns are in common use: a direct private call over the network link, a call to an on-premise API gateway with a private endpoint, a reverse tunnel where an agent inside the data centre dials out and holds a connection open, or a message queue that both sides attach to. The first two require accepting an inbound connection; the last two do not, which usually decides the choice in estates where inbound firewall changes are hard to get approved.

Why did our API get slow after moving to the cloud?

Almost always round trip count rather than bandwidth. A call that took a fraction of a millisecond inside one data centre takes several milliseconds across a link, and interfaces written when calls were effectively free tend to make hundreds of them per user action. Every individual call still looks healthy in the logs. The fix is a coarser endpoint returning the whole payload at once, or a cache on the calling side.

Do you need an API gateway for hybrid cloud integration?

Not necessarily, and buying one first is a common misstep because a gateway does not address call chattiness or the direction connections are initiated in. A gateway earns its place when many consumers need central authentication, rate limiting and a single audited entry point. Place it next to the consumers rather than next to the backend systems, so traffic does not cross the boundary twice on its way to a service in the same environment as the caller.

How do you stop a slow legacy system taking down a cloud application?

Set an explicit read timeout on every call, since several widely used HTTP clients default to waiting indefinitely and a backend that accepts connections without answering will exhaust the caller's threads. Add a circuit breaker that stops calling a failing dependency and returns a degraded response, a bounded connection pool so one slow system cannot consume all capacity, and a retry budget with jitter so clients do not finish off a struggling backend.

What is an idempotency key and why does hybrid integration need one?

A unique value supplied by the caller so the receiving system can recognise a repeated request and return the original result instead of acting twice. It matters across a hybrid boundary because network failures are more frequent there, so calls get retried, and a retried order creation without an idempotency key produces two orders. The receiving side must store the key long enough to cover the caller's full retry window.

Should legacy interfaces be modernised before hybrid integration?

Usually not first. A SOAP endpoint, stored procedure or fixed-width file is still an interface, and a thin wrapper service that translates the payload, holds the credentials, applies timeouts and batches fine-grained calls into one coarse operation is typically a week of work rather than a modernisation programme. Replacing the underlying system is justified when the interface cannot express what is needed, cannot be made safe to retry, or has a throughput ceiling that measurement shows is the real constraint.

Hybrid cloud guide

How do you integrate APIs across a hybrid cloud?

The first instinct is usually to buy an API gateway, and it is usually premature. Nothing about a gateway addresses the two problems that actually bite: an interface designed when calls were free now pays a network round trip for each one, and the direction a connection is initiated in decides whether your security team will ever approve it. Get those right and a plain reverse proxy is often enough. Get them wrong and no gateway saves you.

What actually changes when a call crosses the boundary?

The cost of a round trip. Inside one data centre a call between two services completes in a fraction of a millisecond, so nobody counted them. Across a link to a cloud region the same call takes several milliseconds at best, and the interfaces that were fine become the bottleneck without a single line of them changing.

This is why the classic symptom of a hybrid API project is a page that was instant and is now slow, with every individual call looking healthy in the logs. The calls are healthy. There are simply four hundred of them, and four hundred multiplied by a few milliseconds is a user watching a spinner.

The mechanism is nearly always fine-grained interfaces or lazy loading in an object relational mapper: one query for the list, then one per row. Those patterns were invisible when the database was in the next rack. Moving the caller to a cloud region turns an internal design choice into a user-facing latency problem, and the correct fix is a coarser endpoint that returns the whole payload in one call, not more bandwidth.

Which direction is the hard one?

Cloud calling on-premise, because it requires something in your data centre to accept an inbound connection. On-premise calling out is comparatively easy, since outbound connections through a firewall are already normal. Almost every hard conversation in hybrid API work is really about the inbound direction, and the pattern you choose determines whether that conversation happens at all.

The patterns divide neatly by whether anything has to listen. Direct private calls over the link and an on-premise API gateway both mean opening a listener, even if only to the private range. A reverse tunnel, where an agent inside your network dials out to a cloud endpoint and holds the connection open for traffic to flow back down, means nothing inbound is opened. A message queue or event bus means neither side connects to the other at all, since both attach to a broker.

Choose by what the caller needs. If the cloud application needs a synchronous answer to serve a user, you need a listener or a tunnel. If it needs work to happen eventually, a queue is simpler, survives the on-premise system being down and does not require a firewall change anyone has to sign.

Pattern	Opens inbound?	Latency	If the other side is down	Best for
Direct private call over the link	Yes, to the private range	One round trip	Caller fails immediately	Trusted internal services with a real-time answer
On-prem gateway with private endpoint	Yes, one controlled entry point	One round trip plus proxy	Caller fails, gateway can shed load	Many consumers, central auth and rate limiting
Reverse tunnel from an on-prem agent	No, agent dials out	One round trip	Tunnel drops, calls fail fast	Estates where inbound firewall changes are not approved
Message queue or event bus	No, both sides attach to a broker	Asynchronous	Work waits in the queue	Anything the user does not wait for
Scheduled batch or file transfer	No	Minutes to hours	Next run catches up	Bulk reference data and reporting extracts

Should the gateway sit on-premise or in the cloud?

Put it next to the consumers, not next to the systems. A gateway exists to serve callers, so placing it where the callers are keeps their normal path short and pushes the crossing to the calls that genuinely need to cross.

The failure to avoid has an unlovely name in networking circles: trombone routing, where traffic leaves the cloud, reaches an on-premise gateway, and is proxied straight back to another cloud service. Every hop crosses the link twice, latency triples and you are billed for the leg out. This happens by accident whenever a single central gateway is declared the standard for everything.

Two gateways is a perfectly reasonable answer if the consumer populations are genuinely separate, provided both draw their configuration and policy from the same source. Two gateways that are configured by hand in two places is a different and worse situation, which the configuration drift guide covers.

How do you stop a slow on-prem system taking the cloud app down?

By setting a timeout on every call, which sounds obvious and is very often missing. Several widely used HTTP clients default to no read timeout at all, so a legacy system that accepts connections but stops answering will hold every thread in the calling application until nothing is left to serve anyone. The outage looks like a cloud problem and is not.

Beyond timeouts, the three mechanisms worth the effort are a circuit breaker that stops calling a failing dependency for a while and returns a degraded response, a bounded pool so calls to one slow system cannot consume all the capacity of the caller, and a retry budget so that a struggling backend is not finished off by every client retrying at once. Retries without a budget and without jitter turn a slow dependency into a dead one.

Any retry also needs the receiving operation to be safe to repeat. If the on-premise system creates an order, a retried call creates two, and the usual remedy is an idempotency key supplied by the caller and stored on the receiving side long enough to recognise a repeat. Adding retries without this is how a hybrid integration produces duplicate records nobody can explain.

Do the legacy interfaces need replacing first?

Rarely, and attempting it is how these projects lose a year. A SOAP endpoint, a stored procedure or a fixed-width file is an interface, and wrapping it in a thin service that speaks the shape your cloud application wants is usually a week of work rather than a modernisation programme.

The wrapper earns its place by absorbing the awkwardness in one auditable location: it holds the credentials, translates the payload, applies the timeout, batches the fine-grained calls into one coarse operation and gives you somewhere to log and measure. The legacy system stays exactly as it is, which is also what its owners want.

The case for actually changing the underlying system is narrower: when the interface cannot express what you need, when it cannot be made safe to retry, or when its throughput ceiling is genuinely the constraint. Those are engineering findings, and they should come from measurement rather than from distaste for the technology.

What should you measure before designing anything?

Take one representative user action and count the calls it makes across the boundary, then multiply by the round trip latency you measured on the link. If the result is larger than the latency budget for that action, the design question is settled: you need coarser endpoints, a cache on the cloud side, or a copy of the data. No amount of gateway configuration changes that arithmetic.

Then check the payload sizes in both directions, because the leg leaving the cloud is the one that carries a per-gigabyte charge, and a chatty interface that returns a full object where an identifier would do is paying for it repeatedly.

Finally, ask what the cloud application should do when the on-premise system is unavailable for an hour. If the honest answer is that it should keep working in a reduced form, you have an asynchronous design whether you planned one or not, and it is much cheaper to build that in at the start than to retrofit it after the first incident.

Common questions

How do you call an on-premise API from a cloud application?: Four patterns are in common use: a direct private call over the network link, a call to an on-premise API gateway with a private endpoint, a reverse tunnel where an agent inside the data centre dials out and holds a connection open, or a message queue that both sides attach to. The first two require accepting an inbound connection; the last two do not, which usually decides the choice in estates where inbound firewall changes are hard to get approved.
Why did our API get slow after moving to the cloud?: Almost always round trip count rather than bandwidth. A call that took a fraction of a millisecond inside one data centre takes several milliseconds across a link, and interfaces written when calls were effectively free tend to make hundreds of them per user action. Every individual call still looks healthy in the logs. The fix is a coarser endpoint returning the whole payload at once, or a cache on the calling side.
Do you need an API gateway for hybrid cloud integration?: Not necessarily, and buying one first is a common misstep because a gateway does not address call chattiness or the direction connections are initiated in. A gateway earns its place when many consumers need central authentication, rate limiting and a single audited entry point. Place it next to the consumers rather than next to the backend systems, so traffic does not cross the boundary twice on its way to a service in the same environment as the caller.
How do you stop a slow legacy system taking down a cloud application?: Set an explicit read timeout on every call, since several widely used HTTP clients default to waiting indefinitely and a backend that accepts connections without answering will exhaust the caller's threads. Add a circuit breaker that stops calling a failing dependency and returns a degraded response, a bounded connection pool so one slow system cannot consume all capacity, and a retry budget with jitter so clients do not finish off a struggling backend.
What is an idempotency key and why does hybrid integration need one?: A unique value supplied by the caller so the receiving system can recognise a repeated request and return the original result instead of acting twice. It matters across a hybrid boundary because network failures are more frequent there, so calls get retried, and a retried order creation without an idempotency key produces two orders. The receiving side must store the key long enough to cover the caller's full retry window.
Should legacy interfaces be modernised before hybrid integration?: Usually not first. A SOAP endpoint, stored procedure or fixed-width file is still an interface, and a thin wrapper service that translates the payload, holds the credentials, applies timeouts and batches fine-grained calls into one coarse operation is typically a week of work rather than a modernisation programme. Replacing the underlying system is justified when the interface cannot express what is needed, cannot be made safe to retry, or has a throughput ceiling that measurement shows is the real constraint.