YARP API Gateway

Intro

YARP is Microsoft’s reverse-proxy toolkit for building a .NET edge gateway. It provides routing, destination selection, transforms, health checks, and extensibility without defining business policy. Reach for it when gateway behavior must be owned in ASP.NET Core and configuration alone is not enough.

Minimal gateway

var builder = WebApplication.CreateBuilder(args);
 
builder.Services
    .AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));
 
var app = builder.Build();
app.MapReverseProxy();
app.Run();

{
  "ReverseProxy": {
    "Routes": {
      "orders": {
        "ClusterId": "orders-cluster",
        "Match": { "Path": "/api/orders/{**catch-all}" },
        "Transforms": [
          { "PathRemovePrefix": "/api" }
        ]
      }
    },
    "Clusters": {
      "orders-cluster": {
        "Destinations": {
          "orders-a": { "Address": "https://orders.internal/" }
        }
      }
    }
  }
}

The route matches the public path, the cluster owns destinations and load-balancing policy, and the transform removes the external prefix before forwarding.

Production boundaries

• Authenticate before proxying and authorize by route or endpoint metadata.
• Forward trace context and a stable request ID; do not log bearer tokens or request bodies by default.
• Apply client-facing rate limits at the edge. Keep downstream concurrency limits and bulkheads near the protected dependency.
• Use active or passive destination health only when the signal distinguishes one destination from the rest of the fleet.
• Bound retries to replayable requests. A gateway retry of an uncertain POST needs an end-to-end idempotency contract.

Keep aggregation small and read-oriented. If gateway code starts deciding order eligibility, payment state, or inventory invariants, move that logic to the owning service.

References

• YARP getting started — official registration, configuration, and proxy endpoint setup.
• YARP configuration files — official route, cluster, destination, and transform schema.
• YARP health checks — official active and passive destination health behavior.
• ASP.NET Core rate limiting — official middleware and policy model for edge quotas.