# What is an API gateway, and what should never go in one?

A gateway concentrates the concerns every service shares. That is its value and its risk — the cross-cutting layer becomes a shared bottleneck and a place business logic quietly accumulates.


An API gateway sits in front of your services and handles what they all need: routing, authentication, rate limiting, logging. One place rather than a copy in every service.

The value is genuine — those concerns are tedious, easy to implement inconsistently, and exactly the kind of thing that should exist once. The risk is the same property from a different angle: a component every request passes through becomes a shared point of failure, a deployment bottleneck between teams, and a place where logic accumulates until nobody can change it.

## What we'll cover

- [What belongs in a gateway](#what-belongs-in-a-gateway)
- [What should never go in one](#what-should-never-go-in-one)
- [The gateway becoming a monolith](#the-gateway-becoming-a-monolith)
- [Authentication at the edge](#authentication-at-the-edge)
- [Backend for frontend](#backend-for-frontend)
- [When you do not need one](#when-you-do-not-need-one)
- [Operating it](#operating-it)
- [Versioning what you expose](#versioning-what-you-expose)
- [Automating around the edge with CodeWords](#automating-around-the-edge-with-codewords)
- [What to get right first](#what-to-get-right-first)
- [Frequently asked questions](#frequently-asked-questions)

## What belongs in a gateway

Concerns that are genuinely identical across every service.

**Routing.** Mapping a public path to an internal service, which is the core function.

**Authentication.** Verifying a credential is valid, once, rather than in every service.

**Rate limiting**, which needs a global view that no single service instance has.

**TLS termination**, so services do not each manage certificates.

**Request and response logging**, giving one consistent record of traffic.

**Correlation identifiers**, generated at the edge and propagated, which is what makes tracing possible.

The test: would every service implement this identically? If yes, the gateway is the right home. If services would reasonably differ, it is not.

## What should never go in one

**Business logic.** Any rule specific to a domain belongs in the service that owns the domain, and a gateway containing pricing rules or eligibility checks has taken ownership of something it cannot test properly.

**Authorisation decisions about specific resources.** The gateway can verify who you are; whether you may see this particular record depends on the record, which only the owning service knows.

**Response transformation to suit one client**, which is how a gateway becomes a collection of special cases.

**Orchestration across services.** A gateway calling three services and combining results is a service, and it should be one, with its own repository, tests, and deployment.

**Data access.** A gateway with a database is no longer a gateway.

**Anything one team needs and others do not**, which is the general form of all of the above and the thing to watch for.

## The gateway becoming a monolith

The failure mode, and it happens gradually.

**One special case gets added**, reasonably, because it was faster than changing a service.

**Then another**, by a different team, for a different reason.

**Every team now depends on it**, so every change requires coordination and nobody deploys it casually.

**It becomes the slowest thing to change** in an architecture chosen for independent deployment, which is precisely the property it undermines.

**Nobody owns it.** It is shared infrastructure, which means it is everybody's and therefore nobody's.

**The remedy is a rule about what may go in**, agreed and enforced — because each individual addition is defensible and the aggregate is not.

## Authentication at the edge

Worth being precise, because the common arrangement has a subtlety.

**The gateway verifies the credential** — signature, expiry, issuer — and rejects anything invalid before it reaches a service.

**It passes identity downstream**, typically as a trusted header or a re-signed token.

**Services must not trust that blindly.** If a service can be reached without going through the gateway, a forged header is an authentication bypass.

**So either make the gateway the only route**, at the network level, or have services verify independently.

**Authorisation stays in the service.** Verifying who somebody is and deciding what they may do are different questions, and the second depends on the resource.

**Handle the token that expires mid-request**, which is a real case in long-running calls and produces confusing intermittent failures.

## Backend for frontend

A pattern frequently confused with a gateway and genuinely different.

**A backend for frontend serves one client type** — the mobile application, the web application — aggregating and shaping responses for that client's needs.

**It contains logic** specific to that client, legitimately, which is exactly what a gateway should not.

**It is owned by the team building that client**, and deployed on their schedule.

**It sits behind the gateway**, not instead of it, so the cross-cutting concerns still happen once.

**Use one when clients genuinely need different shapes.** A mobile client wanting fewer round trips and smaller payloads is a real requirement, and satisfying it by adding special cases to a shared gateway is what produces the monolith above.

## When you do not need one

**A single service.** The concerns are handled in that service, and a gateway adds a hop and a component to operate.

**A managed platform that already provides it.** Cloud load balancers and hosting platforms frequently handle TLS, routing, and basic rate limiting, and adding another layer duplicates them.

**Internal-only traffic** where the services trust each other and a service mesh handles the cross-cutting concerns closer to the calls.

**Low traffic and a small team**, where the operational cost of another component exceeds the duplication it removes.

**When nobody will own it.** An unowned gateway is a shared dependency that nobody upgrades and everybody blames.

## Operating it

**It is in every request path**, so its availability is your availability and its latency is added to everything.

**Watch its own resource use**, since a gateway under pressure degrades everything simultaneously and the symptom looks like every service being slow at once.

**Deploy it carefully**, with the same or more caution than any service, because a bad gateway deployment is a total outage rather than a partial one.

**Keep the configuration in version control** and deploy it through the same route as code, since routing rules are logic and a rule changed in a console has no history.

**Test the routes.** A path that matches nothing returns a confusing error, and route configuration is easy to get subtly wrong.

**Have a bypass plan.** Knowing how to route around the gateway during an incident is worth establishing before the incident.

## Versioning what you expose

A gateway is where the public shape of your system is decided, which makes it the natural place to think about versions.

**The path is a contract.** Once a client depends on it, changing it is a breaking change regardless of what happens behind.

**The gateway lets internal structure change without the public shape changing**, which is one of its better properties — a service split in two behind an unchanged path is invisible to callers.

**Version at the edge, not per service.** Consumers care about your API's version, not about which service handles which part.

**Support both versions during a transition**, routed differently, which the gateway makes straightforward and which is otherwise awkward.

**Know who is using what.** Deprecating a version requires knowing which clients remain on it, and the gateway's logs are where that lives.

**Announce deprecations with a date and remind people**, since clients do not migrate in response to documentation alone.

## Automating around the edge with CodeWords

Much of what people are tempted to put in a gateway — notifying a system, recording something externally, reacting to a pattern in traffic — is integration work rather than edge concerns. CodeWords connects to more than 3,000 integrations.

1. Open [CodeWords](https://codewords.agemo.ai) and start a new automation.
2. Describe what should happen in plain language to Cody, the automation builder.
3. Describe the exceptions explicitly.
4. Connect the systems involved once and reuse the connections.

You describe the outcome; Cody builds it, connects it, and deploys it. The free plan covers light use, with Pro at $39 per month and Business at $100 per month as usage grows; details are on the [pricing page](/pricing).

## What to get right first

An agreed, written rule about what may go into the gateway — and an owner who applies it. Every individual special case is defensible, which is exactly why the accumulation happens, and a rule is the only thing that reliably prevents a shared edge component becoming the slowest part of an architecture chosen for independence.

Two habits make the difference. Generate a correlation identifier at the edge and propagate it, since that single piece of plumbing is what makes tracing possible across everything behind it. And keep routing configuration in version control deployed like code, because routing is logic and a rule changed in a console has no history and no review.

## Frequently asked questions

### What belongs in an API gateway?

Concerns every service would implement identically: routing, credential verification, rate limiting, TLS termination, logging, and correlation identifiers. If services would reasonably differ on something, it does not belong there.

### Why should business logic stay out?

Because it belongs to a domain, and a gateway cannot test it properly or own it meaningfully. Each addition is defensible, and the aggregate turns a shared component into the slowest thing to change in the architecture.

### Can the gateway handle authorisation?

It can verify who you are. Whether that person may see a specific record depends on the record, which only the owning service knows — so authentication at the edge and authorisation in the service is the workable split.

### Is it safe for services to trust a header from the gateway?

Only if the gateway is genuinely the only route to them. Otherwise a forged header is an authentication bypass, so either enforce that at the network level or have services verify independently.

### What is a backend for frontend?

A service serving one client type, aggregating and shaping responses for it, owned by that client's team and sitting behind the gateway. It legitimately contains client-specific logic, which is what keeps that logic out of the shared layer.

### When do I not need a gateway?

With a single service, where a managed platform already provides routing and TLS, for internal traffic handled by a mesh, or where nobody will own it — an unowned gateway is a dependency everybody blames and nobody upgrades.

### What is the operational risk?

It is in every request path, so its availability is yours and its latency is added to everything. A bad deployment is a total outage rather than a partial one, which is why it deserves more caution than a service.

### Should API versions be handled at the gateway?

Yes — consumers care about your API's version rather than which service handles which part. The gateway can route two versions simultaneously during a transition, which is awkward to arrange otherwise.

### How do I know who is still on an old version?

The gateway's logs, which is the only place that view exists. Deprecating without it means either guessing or leaving the old version running indefinitely, and both are common.

## Related reading

- [Service mesh](/blog/what-is-a-service-mesh)
- [API rate limiting explained](/blog/api-rate-limiting-explained)
- [API authentication methods](/blog/api-authentication-methods-explained)