API Gateway

An API gateway is one address that clients call, which forwards each request to whichever service owns it. The browser asks api.example.com for an order; the gateway decides that orders lives at orders.internal and passes the request on.

The problem it solves is what clients otherwise have to know. Without it, a front end holds the address of every service, handles a different authentication setup for each, needs cross-origin permission from each, and has to be redeployed when a service moves or splits. Concerns that are identical for every service — checking the token, limiting the request rate, terminating TLS, attaching a correlation identifier — end up implemented several times, slightly differently.

### What the client sends
GET https://api.example.com/orders/8421 HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

### What the orders service receives
GET http://orders.internal:8080/orders/8421 HTTP/1.1
Accept: application/json
X-Correlation-Id: 0f4c1a7e-6b2d-4f19-9a33-1c7e85d2b4aa
X-Forwarded-For: 203.0.113.42
X-Forwarded-Proto: https
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

• The client knows one host name. Services can move, be renamed, or be split in two without the front end being rebuilt.
• The token was validated at the edge, once. Services behind the gateway still check it, because an internal caller can reach them without passing through the gateway at all.
• The correlation and trace headers are attached here because this is the first point that sees the request. Add them further in and every log line before that point is unlinked from the rest.
• The caller's address now only exists in X-Forwarded-For. Services behind the gateway have to be configured to read forwarded headers, or every log entry records the gateway as the client and rate limiting by address becomes meaningless.
• Whatever the gateway adds, it must also remove from inbound requests. If a client can send its own X-Correlation-Id it can poison your logs; if it can send a header your services trust for identity, it can act as anyone. Strip first, then set.

{
  "ReverseProxy": {
    "Routes": {
      "orders": {
        "ClusterId": "orders",
        "Match": { "Path": "/orders/{**remainder}" },
        "AuthorizationPolicy": "authenticated",
        "RateLimiterPolicy": "per-user",
        "Transforms": [ { "RequestHeaderRemove": "X-Correlation-Id" } ]
      },
      "invoices": {
        "ClusterId": "invoicing",
        "Match": { "Path": "/invoices/{**remainder}" },
        "AuthorizationPolicy": "finance-only",
        "RateLimiterPolicy": "per-user"
      }
    },
    "Clusters": {
      "orders": {
        "LoadBalancingPolicy": "RoundRobin",
        "HealthCheck": {
          "Active": { "Enabled": true, "Path": "/health/ready", "Interval": "00:00:10" }
        },
        "Destinations": {
          "orders-1": { "Address": "http://orders-1.internal:8080/" },
          "orders-2": { "Address": "http://orders-2.internal:8080/" }
        }
      },
      "invoicing": {
        "Destinations": {
          "invoicing-1": { "Address": "http://invoicing.internal:8080/" }
        }
      }
    }
  }
}

• A route matches a path and names a cluster; a cluster lists where that service actually runs. Adding a second copy of orders is one line of configuration rather than a code change anywhere.
• The authorisation policy is per route, so a valid token without the finance claim is refused at the edge and the invoicing service never sees the request. The service still applies its own rules, because this is a filter and not a substitute.
• Active health checks take a restarting instance out of rotation. Without them the gateway keeps sending traffic to a process that is not ready and the client sees intermittent errors for as long as the restart takes.
• The header removal is a trust boundary in one line. The gateway sets the correlation identifier, so any value the client supplied has to go first.
• This being configuration is both the appeal and the risk. A route change can ship without a build — and also without a compiler, a test or a code review unless you insist on one. Keep it in version control and treat it as code.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication().AddJwtBearer();

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("authenticated", p => p.RequireAuthenticatedUser())
    .AddPolicy("finance-only", p => p.RequireClaim("role", "finance"));

builder.Services.AddRateLimiter(options =>
{
    options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    options.AddPolicy("per-user", context => RateLimitPartition.GetFixedWindowLimiter(
        partitionKey: context.User.FindFirst("sub")?.Value ?? "anonymous",
        factory: _ => new FixedWindowRateLimiterOptions
        {
            PermitLimit = 120,
            Window = TimeSpan.FromMinutes(1),
        }));
});

builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

app.UseForwardedHeaders();
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
app.MapReverseProxy();

app.Run();

• Token validation and the policies are declared once. A new service placed behind the gateway inherits them by being routed through, rather than by copying startup code.
• The rate limit is keyed on the user identifier from the token. Keying on the caller's address instead throttles an entire office as a single client, which is a support call waiting to happen.
• Middleware order is load-bearing. Forwarded headers first, so everything after it sees the real caller. Authentication before authorisation, because a policy needs an identity. Rate limiting after both, so the limit has a user to count against.
• The anonymous fallback deserves a second look before production: one shared partition means every unauthenticated caller competes for the same allowance, which is either the protection you want or a denial of service you built yourself.
• This file is short and should stay short. Everything in it applies to every service behind it, so each addition is a change to all of them at once.