Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Gateway Offloading

Move the work every service does the same way, and that needs no knowledge of the domain, into the gateway: which concerns qualify, how a check done at the gateway reaches the services, the network rule that keeps it honest, where TLS ends, and what the services still decide.

"Can we delete this middleware now?"

The pull request on the Search service of a property-listings platform was forty lines, all of them deletions. Its description said: the gateway validates tokens now, so Search no longer needs its own copy of the check. The platform runs a dozen services, listings, search, photos, agent messaging, viewing bookings and more, and until that quarter each carried its own token validation, compression and TLS certificates, written and updated by each team on its own schedule.

The reviewer did not object to deleting the code. She asked three questions. Once the check is gone, how does Search know who is calling? What stops a request from reaching Search without passing the gateway? And which checks was Search doing that the gateway cannot do for it? Their answers decide whether moving a check to the gateway keeps it or quietly loses it.

The move itself is Gateway Offloading: taking work that every service does the same way out of the services and doing it once, at the gateway in front of them. Which duties usually sit at that front door, and what it costs to run one, is API gateway & the edge; this article is about the move and what it leaves behind.

Two tests a concern must pass

A concern can move when it passes two tests. Every service needs it done the same way, so one implementation serves all twelve, with settings that can differ per route. And the gateway can do it with what it already holds, the traffic passing through, the caller's credentials and its own settings and counters, without knowing anything about listings, photos or bookings.

Token validation passes both: Search and Bookings check a signature, an expiry and an audience the same way, even if each expects its own audience. So does compressing responses, and so does a coarse ceiling on requests per client (the counting itself is Rate limiting). Caching passes only in part. The public page of a listing is the same for every visitor and can be cached at the gateway for a minute; a saved-searches page is different for every signed-in user, and a shared cache that stores it under one key can serve one user's saved searches to the next. Which responses may be stored, and for whom, is decided by the headers in HTTP caching: Cache-Control, ETags & revalidation.

Other checks fail the second test however general they sound. "An agent may edit only their own listings" needs to know who owns listing 48213, which only the Listings service knows. "A free account may have three active listings" needs a count of that account's listings and changes whenever the pricing does. Both stay in the services.

How the identity reaches the service

Search still needs to know the caller: saved searches belong to a user. When the gateway has validated the token, it passes the result on, and there are two common ways to do it.

The simpler one is a header. The gateway sets X-User-Id on the request it forwards, and Search reads the user from there instead of from the token. It works only if the gateway also removes any X-User-Id the client sent. Otherwise:

  1. A client sends a request with a valid token for user 7 and adds its own header X-User-Id: 1001.
  2. The gateway validates the token, which is genuine, and forwards the request with the client's header untouched.
  3. Search reads X-User-Id, finds 1001, and returns user 1001's saved searches to user 7.

So the gateway strips the header from every incoming request, on every route, before setting its own. The other way is for the gateway to forward a short-lived internal token it signs itself, holding the user id and whatever else the services need; each service verifies the gateway's signature with a public key, and checks the expiry and that the token is meant for it. That costs a signature check per request, but a service then accepts only identities the gateway minted, rather than trusting any header that arrives.

Checked once, passed on

The gateway ends the client's TLS, validates the token and forwards the caller's identity; each service decides what that caller may do.

No way around the gateway

The reviewer's second question is the one that matters most. Once Search trusts the gateway's header, anyone who can reach Search directly can claim to be anyone. So a service that trusts the identity header must accept it only on connections it can tie to the gateway, by the gateway's addresses or a certificate issued to the gateway; a private network alone is not enough, since other callers share it. Any other caller has to authenticate in its own way.

That guarantee erodes in quiet ways. During a migration someone gives Photos a public load balancer "for an afternoon". A reporting job inside the network calls Bookings directly, carries no identity at all, and Bookings has to decide what that means. Each is a path to a service that never met the gateway's check. How calls between services prove who they are, with mutual TLS, is Service discovery & the mesh.

Where TLS ends

Ending the client's TLS at the gateway is itself an offload: the public certificates live and are renewed in one place. It is also a precondition for the rest, since the gateway can read the path, check the token and compress the response only once the request is decrypted. Beyond the gateway the platform had a choice: forward plain HTTP inside its private network, or open a new TLS connection to each service. It re-encrypts, because that network also carries the reporting job and engineers' tools, and a request carrying a user's identity should not cross it readable; the price is certificates back on every service.

Settings everyone shares

Offloaded work runs on settings the platform team owns, such as a 1 MB default limit on request size. When Photos needed 30 MB for an agent's batch of pictures, the answer was an override on that one upload route, owned by the Photos team, not a higher limit for every service. Requests of another kind need a no. Someone asked the gateway to hide listings from agents whose licence has expired, because the gateway sees every request; it would have needed the licence register, and every change to the rule a gateway release.

Watch outCommon mistake: letting business logic creep into the gateway alongside the cross-cutting concerns, turning it into a second application layer that every service change must also be coordinated with (and deployed through).

What Search still decides

After the deletion, the gateway knows the token is valid and who the caller is, not what that caller may see or change. Whether user 7 may read saved search 312 is still Search's decision, made against its own data, on every request. A valid token says who is calling, not which resources they may touch, and a service that skips that check because "the gateway handles auth" lets any signed-in user read any other user's data by changing an id in the path.

Revoking a token before it expires is Sessions vs tokens: JWT, refresh & revocation, and floods or crafted attacks need the layers in Edge protection: WAF, DDoS & defence in depth.

The question for every gateway rule

Each rule on the gateway should survive one question: would it have to change if the listings business changed its rules? TLS, the token check and a coarse rate limit would not; an ownership check, a listing quota or the licence filter would, and that is the sign they belong to a service. The API Gateway Patterns Challenge asks for a Gateway Offloading node beside routing and aggregation, with backends left free of the cross-cutting work, in at most 10 nodes. Ask the question of every responsibility you put on that node, and ask the reviewer's other two of each Service behind it: how it learns who is calling, and whether anything reaches it without passing the gateway.

Practice this