If you’re building microservices with .NET, you’ll eventually need a reliable API Gateway to route traffic, apply security, and centralize cross‑cutting concerns.

Microsoft’s YARP (Yet Another Reverse Proxy) is a powerful, production‑ready reverse proxy built specifically for ASP.NET Core.

In this article, we’ll walk through a complete working sample of a YARP API Gateway using .NET 10, including:

• Solution architecture
• Creating downstream services
• Configuring YARP routing & load balancing
• Adding transforms and health checks
• Running the full system locally

1. Architecture Overview

Our sample contains three projects:

• Gateway → YARP reverse proxy
• Orders API → downstream microservice
• Products API → downstream microservice

Client → YARP Gateway → Microservices

The gateway will:

• Route /orders/* → Orders API
• Route /products/* → Products API
• Provide centralized entry point for future auth, caching, logging, etc.

2. Create the Solution

Open terminal and run:

dotnet new sln -n YarpSample

# Create gateway
dotnet new web -n gateway
cd gateway
dotnet add package Yarp.ReverseProxy
cd ..

# Create microservices
dotnet new webapi -n orders-api --no-https
dotnet new webapi -n products-api --no-https

# Add to solution
dotnet sln add gateway orders-api products-api

3. Build Downstream Services

Orders API

orders-api/Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();

app.MapGet("/orders", () => new[]
{
    new { Id = 1, Item = "Laptop", Price = 1200 },
    new { Id = 2, Item = "Mouse", Price = 25 }
});

app.Run("http://localhost:5001");

Products API

products-api/Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();

builder.Services.AddSwaggerGen();

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();

app.MapGet("/products", () => new[]
{
    new { Id = 1, Name = "Keyboard" },
    new { Id = 2, Name = "Monitor" }
});

app.Run("http://localhost:5002");

Run both services:

dotnet run --project orders-api
dotnet run --project products-api

4. Configure the YARP Gateway

Install package

cd gateway
dotnet add package Yarp.ReverseProxy

appsettings.json

{
  "ReverseProxy": {
    "Routes": {
      "orders-route": {
        "ClusterId": "orders-cluster",
        "Match": {
          "Path": "/orders/{**catch-all}"
        }
      },
      "products-route": {
        "ClusterId": "products-cluster",
        "Match": {
          "Path": "/products/{**catch-all}"
        }
      }
    },
    "Clusters": {
      "orders-cluster": {
        "LoadBalancingPolicy": "RoundRobin",
        "Destinations": {
          "orders-api": {
            "Address": "http://localhost:5001/"
          }
        }
      },
      "products-cluster": {
        "LoadBalancingPolicy": "RoundRobin",
        "Destinations": {
          "products-api": {
            "Address": "http://localhost:5002/"
          }
        }
      }
    }
  }
}

Program.cs

using Yarp.ReverseProxy;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.MapReverseProxy();

app.Run("http://localhost:5000");

5. Test the Gateway

Start the gateway:

dotnet run --project gateway

Now test endpoints:

• Orders → http://localhost:5000/orders
• Products → http://localhost:5000/products

Requests flow through YARP → downstream service → response to client.

6. Adding Transforms (Optional)

Example: add header before forwarding.

"Transforms": [
  { "RequestHeader": "X-Gateway", "Set": "YARP" }
]

This enables:

• tracing
• auditing
• gateway identification

7. Health Checks & Resilience

YARP supports active and passive health checks.

Example cluster config:

"HealthCheck": {
  "Active": {
    "Enabled": true,
    "Interval": "00:00:10",
    "Timeout": "00:00:05",
    "Policy": "ConsecutiveFailures",
    "Path": "/health"
  }
}

This ensures traffic only routes to healthy services.

8. Why Use YARP Instead of Ocelot or Nginx?

Advantages of YARP:

• Built by Microsoft for ASP.NET Core
• Fully programmable in C#
• High performance & production ready
• Native integration with .NET middleware

Perfect for cloud‑native microservices.

9. Next Steps for Production

Consider adding:

• JWT authentication at gateway
• Rate limiting
• Distributed tracing (OpenTelemetry)
• Service discovery (Consul, Kubernetes)
• Caching layer

Conclusion

You now have a fully working YARP API Gateway on .NET 10 with:

• Multiple microservices
• Routing & load balancing
• Transforms and health checks

This setup is a strong foundation for scalable .NET microservices architecture.