API Gateway Architecture Done Right

API gateways collect responsibilities the way junk drawers collect batteries. A small transformation added “just this once” for a specific client integration. Business logic for a special case that would be “easier to handle at the edge.” Data aggregation because the mobile client needed it and a proper BFF wasn’t ready yet. You know exactly how this story ends.

Six months later, the gateway has business rules only two engineers understand. One of them just left. There’s aggregation logic that can’t scale on its own. Deployment coupling so tight that any API response change needs a gateway release. The front desk receptionist who started sorting mail, fixing the printer, doing everyone’s accounting, and is now the bottleneck for the entire building.

The opposite failure is just as common. Gateway configured as a thin proxy that forwards everything to a single backend. No cross-cutting value. Just a network hop and a deployment dependency for nothing. A front desk that waves everyone through without checking badges.

The Gateway’s Actual Job

A narrow responsibility set, strictly kept. The front desk checks badges, directs visitors, and logs who enters. That’s it. Application security at the edge depends on this boundary staying clean.

Complete list. If someone on your team is tempted to add more, the answer is no. Every extra responsibility is a step toward the edge monolith. The moment the receptionist starts doing accounting, the lobby is unattended.

The distinction between authentication (does this token represent a valid user?) and authorization (can this user access this resource?) is where most teams blur the line first. Authentication belongs at the gateway. Authorization needs domain context that only the backend service has. The front desk checks your badge is real. Only the department head decides whether you’re allowed in the meeting.

The BFF Pattern: Aggregation Done Right

Different clients need different data shapes. Mobile needs compact responses with minimal payloads. Web needs rich data for complex UI rendering. Partners need stable contracts that don’t break when internal services change. One front desk, three different tours.

A dedicated BFF per client type aggregates and transforms independently. The mobile team updates their BFF without coordinating with web or gateway teams. If gateway changes need cross-team coordination, the gateway has swallowed too much. Microservice architectures were supposed to fix that.

The BFF adds 10-30ms of latency. Worth it when it kills over-fetching and cuts client-side processing. Not worth it when a single backend already returns exactly what the client needs. Don’t build a personal assistant for someone who only asks for directions.

Rate Limiting Design

Rate limit by IP for unauthenticated traffic (100 req/min), by API key for authenticated traffic (1,000-10,000 depending on tier). Return 429 with Retry-After, not 503. The status code difference matters because well-behaved clients retry on 429 with backoff but treat 503 as a service failure. The difference between “please wait” and “something’s broken.”

# Gateway rate limiting config
rate_limiting:
  unauthenticated:
    limit: 100
    window: 60s
    key: client_ip
    response: 429  # with Retry-After header
  authenticated:
    tiers:
      free:       { limit: 1000,  window: 60s, key: api_key }
      pro:        { limit: 5000,  window: 60s, key: api_key }
      unlimited:  { limit: 10000, window: 60s, key: api_key }

Below 1% rate limited: set correctly. Above 5%: limits are too tight or traffic patterns shifted. Alert on sudden jumps. Connect to your observability stack so rate limit events line up with latency spikes. A surge in 429s that doesn’t match a traffic spike means your limits are wrong, not your users.

Gateway Observability

The gateway sees 100% of inbound traffic. The security camera at the front door. Five metrics matter: request rate by endpoint (alert on 2x jump from baseline), error rate by status code (separate 4xx client errors from 5xx server errors), latency at P50/P95/P99, upstream health from backend health check failures, and rate limit hit rate as a percentage of total traffic.

Inject trace IDs at the gateway. One identifier connects the client request through every backend hop to the exact failure point. Structured access logs (path, method, status, latency, client ID, trace ID) resolve most “your API is broken” tickets in minutes instead of hours. Teams with gateway dashboards resolve incidents faster because the gateway is the one point with complete traffic visibility. API integration engineering starts with this visibility layer.

Version Routing and API Sunset

Route /v1/users to the v1 service instance, /v2/users to v2. The gateway separates public API versions from internal service versions, which means v1 and v2 can be completely different implementations behind the same hostname. Inject Sunset and Deprecation headers automatically on deprecated versions so clients get advance notice in every response.

Old versions are attack surface. That 2019 endpoint “nobody uses” still gets 47 requests per day from an undocumented integration. Ghosts in the building. Leaving it running means maintaining security patches for code that should have been torn down years ago.

Security at the Edge

Four controls, layered. WAF blocks OWASP top 10 attacks at the edge with 1-3ms per request overhead. The bouncer who knows what trouble looks like. mTLS between gateway and backends gives you zero-trust internal communication. Automate certificate rotation from day one with short-lived certificates, because manual rotation is the rotation that doesn’t happen. (It never happens.)

JWT validation at the gateway handles authentication. Authorization stays at the backend where domain logic lives. Don’t push authorization into the gateway. It needs context (ownership, roles, resource state) that only the service has. The gateway confirms you work here. Only the service decides whether you belong in the room.

Bot detection analyzes header ordering, TLS fingerprints, and timing patterns. A cloud-native architecture processing heavy request volumes will find a surprising share of traffic is bots, and that share grows with API popularity. Your most loyal “users” might not be human.

That “just this once” transformation from six months ago? Rip it out. Clear contract: route, authenticate, rate-limit. Everything else belongs somewhere else. The front desk checks badges and points visitors to the right floor. Nothing more.