API Gateway with YARP

The problem: a mobile app with three services

Our shop has three services: catalog, orders and payment. The mobile app must talk to all three. If the app connects to the services directly:

1. The app must know the address of every service. If tomorrow we split the order service in two, we must publish a new app version and wait for users to install it.
2. Shared jobs are repeated. Each service must check the token on its own, set rate limits, and have CORS settings. Each team does this a little differently.
3. All services are visible from the internet. Each service is an entry door for attacks.

The idea: one entry door

An API Gateway sits in front of all services. The user knows only one address. The services are only on the internal network.

Jobs that the Gateway does:

1. Routing. Addresses that start with “/api/orders” go to the order service.
2. Authentication. It checks the token once. A request without a valid token does not reach the services.
3. Rate limiting. It stops a user who sends a thousand requests in one minute.
4. Load balancing. If the order service has three instances, it spreads requests between them and leaves out an unhealthy instance.
5. Request changes. For example, it removes the “/api” prefix from the address or adds a header.

The path of one request

Let us follow one request. A customer opens order number 42:

1. If the token is not valid, the Gateway returns code 401 right at the start.
2. If the user has gone over their quota, they get code 429.
3. Then the Gateway finds a route that matches the address.
4. It changes the address for the target service.
5. It picks one of the healthy instances of the order service and sends the request.

So the order service only sees correct requests, and it focuses on its own main job.

The YARP library

The name YARP is short for Yet Another Reverse Proxy. It is an open-source library from Microsoft, built on ASP.NET Core. So our Gateway is a normal ASP.NET Core app, and everything we know (Middleware, authentication, Rate Limiting, logging) works in it.

YARP has three main concepts:

• Route. An address pattern, like “/api/orders/” and anything after it. Each Route points to a Cluster.
• Cluster. The group of instances of one service, with the load balancing method and the health check.
• Destination. The real address of each instance.

Code

The Gateway app

using System.Threading.RateLimiting;

var builder = WebApplication.CreateBuilder(args);

// JWT settings come from configuration (Authentication:Schemes:Bearer).
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
    o.AddPolicy("customer", p => p.RequireAuthenticatedUser()));

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

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

var app = builder.Build();

app.UseAuthentication();   // first: who is the user?
app.UseAuthorization();
app.UseRateLimiter();      // must run before the proxy
app.MapReverseProxy();

app.Run();

Route settings

{
  "ReverseProxy": {
    "Routes": {
      "catalog": {
        "ClusterId": "catalog",
        "Match": { "Path": "/api/catalog/{**rest}" },
        "Transforms": [ { "PathRemovePrefix": "/api" } ]
      },
      "orders": {
        "ClusterId": "orders",
        "AuthorizationPolicy": "customer",
        "RateLimiterPolicy": "per-user",
        "Match": { "Path": "/api/orders/{**rest}" },
        "Transforms": [ { "PathRemovePrefix": "/api" } ]
      }
    },
    "Clusters": {
      "catalog": {
        "Destinations": {
          "c1": { "Address": "http://catalog-1:8080/" },
          "c2": { "Address": "http://catalog-2:8080/" }
        }
      },
      "orders": {
        "LoadBalancingPolicy": "RoundRobin",
        "HealthCheck": {
          "Active": {
            "Enabled": true,
            "Interval": "00:00:10",
            "Timeout": "00:00:05",
            "Policy": "ConsecutiveFailures",
            "Path": "/health/ready"
          }
        },
        "Destinations": {
          "o1": { "Address": "http://orders-1:8080/" },
          "o2": { "Address": "http://orders-2:8080/" }
        }
      }
    }
  }
}

These settings say:

• The catalog is open to everyone. Orders are only for signed-in users, and each user has a quota of one hundred requests per minute.
• The address “/api/orders/42” reaches the order service as “/orders/42”.
• The health of the order instances is checked every ten seconds. An instance that fails to answer several times in a row is left out.

Important rules

1. Do not put business logic in the Gateway. Pricing or order rules belong in the service. If the Gateway knows business rules, every small change must be made in two places.
2. Services must check permissions too. The Gateway only says “this user is signed in”. The order service must check “is this user allowed to see order 42?”. If one day someone reaches the service directly from inside the network, it must not be defenseless.
3. Run several instances of the Gateway. All traffic passes through it. If there is only one instance and it goes down, the whole shop goes down.
4. Keep it light. Each request has one extra network step. Heavy work in the Gateway makes all services slow.
5. Think about a separate Gateway for each kind of user. If the mobile app and the website have very different needs, the BFF (Backend for Frontend) pattern means one Gateway for each. This way the mobile team does not wait for the web team.
6. Create the request ID right here. A trace ID that starts at the Gateway makes it possible to follow one request across all services.

Common mistakes

When to use a Gateway?