Building modern distributed applications requires a robust API Gateway to manage traffic, security, and routing.

YARP (Yet Another Reverse Proxy) is Microsoft's high-performance reverse proxy built on ASP.NET Core. You can use it as a flexible and extensible foundation for building API Gateways in .NET.

It features high performance and integrates seamlessly with ASP.NET Core. And it's pretty simple to set up.

If you are using Ocelot, consider that YARP provides improved performance and more efficient integration with ASP.NET Core, making it a stronger choice for .NET environments.

If you use complex API Gateways such as Traefik or Envoy, YARP can serve as a simpler solution if advanced features are unnecessary.

In this post, we will explore:

• Getting Started with YARP
• Using YARP as an API Gateway for Microservices
• Load Balancing Across Service Instances
• Centralized Authentication and Authorization
• Request Routing and Path Rewriting
• YARP as Backend-For-Frontend (BFF) Gateway
• Traffic Shaping and Rate Limiting
• Observability and Centralized Logging
• Additional Scenarios You Might Consider

Let's dive in.

YARP is a reverse proxy toolkit developed by Microsoft for building fast and customizable proxy servers using ASP.NET Core infrastructure.

Unlike traditional API Gateway solutions with fixed features, YARP offers building blocks you can compose for your needs.

Why choose YARP:

• Built on ASP.NET Core, using the same high-performance infrastructure
• Fully extensible through middleware and custom transformations
• Configuration can be loaded from appsettings.json, C# code, or external sources
• Supports dynamic configuration updates without restarting the application
• Integrates seamlessly with existing ASP.NET Core features like authentication, logging, and health checks
• Open source and actively maintained by Microsoft
• Available as a Docker container

Getting started with YARP is easy.

First, create a new ASP.NET Core Web API project and install the YARP NuGet package:

bash
1dotnet add package Yarp.ReverseProxy

Here is how to configure YARP in your Program.cs file:

csharp
1var builder = WebApplication.CreateBuilder(args);
2
3// Add YARP services
4builder.Services.AddReverseProxy()
5    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));
6
7var app = builder.Build();
8
9// Map YARP routes
10app.MapReverseProxy();
11
12app.Run();

This minimal setup lets YARP read the reverse proxy configuration from appsettings.json and sets up all the necessary routing.

Let's create a simple reverse proxy that forwards requests to a backend service.

Add this configuration to your appsettings.json:

json
1{
2  "Logging": {
3    "LogLevel": {
4      "Default": "Information",
5      "Microsoft.AspNetCore": "Warning"
6    }
7  },
8  "ReverseProxy": {
9    "Routes": {
10      "products-route": {
11        "ClusterId": "shipments-cluster",
12        "Match": {
13          "Path": "/products/{**catch-all}"
14        }
15      }
16    },
17    "Clusters": {
18      "shipments-cluster": {
19        "Destinations": {
20          "destination1": {
21            "Address": "https://localhost:5001/"
22          }
23        }
24      }
25    }
26  }
27}

In this configuration:

• Routes define how incoming requests are matched and which cluster handles them
• Match.Path uses pattern matching - {**catch-all} captures everything after /products/
• Clusters define groups of backend destinations
• Destinations specify the actual backend service addresses

When a client sends a request to https://127.0.0.1:5000/products/123 (assuming you run your YARP application on port 5000), YARP forwards it to https://localhost:5001/products/123.

You can also configure YARP entirely in code if you prefer:

csharp
1var builder = WebApplication.CreateBuilder(args);
2
3builder.Services.AddReverseProxy()
4    .LoadFromMemory(
5        routes: new[]
6        {
7            new RouteConfig
8            {
9                RouteId = "products-route",
10                ClusterId = "shipments-cluster",
11                Match = new RouteMatch
12                {
13                    Path = "/products/{**catch-all}"
14                }
15            }
16        },
17        clusters: new[]
18        {
19            new ClusterConfig
20            {
21                ClusterId = "shipments-cluster",
22                Destinations = new Dictionary<string, DestinationConfig>
23                {
24                    {
25                        "destination1",
26                        new DestinationConfig
27                        {
28                            Address = "https://localhost:5001/"
29                        }
30                    }
31                }
32            }
33        });
34
35var app = builder.Build();
36
37app.MapReverseProxy();
38
39app.Run();

This approach provides identical functionality with full code control, useful for dynamic configurations.

YARP supports loading the proxy configuration from multiple sources. LoadFromConfig may be called multiple times, referencing different IConfiguration sections from different config files, or it may be combined with a different config source, such as InMemory.

In YARP, code-based configuration loaded via IProxyConfigProvider generally takes priority or can override appsettings.json.

Now that you have YARP set up, let's explore real-world scenarios where it's helpful.

In a microservices architecture, you have multiple services, each handling a specific business boundary. An API Gateway acts as a single entry point for all client requests, routing them to the appropriate backend service.

Without an API Gateway, clients need to know the address of every microservice. This creates tight coupling and makes it difficult to change service locations or add new services.

YARP solves this by providing a unified endpoint that routes requests based on path patterns.

Let's build an API Gateway for three microservices:

• Shipment Service - manages shipments and their states (runs on port 5001)
• Stock Service - handles stock updates (runs on port 5002)
• User Service - manages users (runs on port 5003)

Here is the complete appsettings.json configuration:

json
1{
2  "Logging": {
3    "LogLevel": {
4      "Default": "Information",
5      "Microsoft.AspNetCore": "Warning",
6      "Yarp": "Information"
7    }
8  },
9  "ReverseProxy": {
10    "Routes": {
11      "products-route": {
12        "ClusterId": "shipments-cluster",
13        "Match": {
14          "Path": "/api/shipments/{**catch-all}"
15        }
16      },
17      "orders-route": {
18        "ClusterId": "stocks-cluster",
19        "Match": {
20          "Path": "/api/stocks/{**catch-all}"
21        }
22      },
23      "customers-route": {
24        "ClusterId": "users-cluster",
25        "Match": {
26          "Path": "/api/users/{**catch-all}"
27        }
28      }
29    },
30    "Clusters": {
31      "shipments-cluster": {
32        "Destinations": {
33          "products-service": {
34            "Address": "https://localhost:5001/"
35          }
36        }
37      },
38      "stocks-cluster": {
39        "Destinations": {
40          "orders-service": {
41            "Address": "https://localhost:5002/"
42          }
43        }
44      },
45      "users-cluster": {
46        "Destinations": {
47          "customers-service": {
48            "Address": "https://localhost:5003/"
49          }
50        }
51      }
52    }
53  }
54}

With this configuration:

• Requests to https://gateway:5000/api/shipments/123 route to the Shipments Service
• Requests to https://gateway:5000/api/stocks/456 route to the Stocks Service
• Requests to https://gateway:5000/api/users/789 route to the Users Service

The {**catch-all} pattern captures the entire path after the prefix, including any additional segments and query strings.

When your application scales, you may need to run multiple instances of the same service to handle increased traffic. Load balancing spreads incoming requests across these service instances to ensure no single instance becomes overwhelmed.

YARP provides built-in load balancing strategies that automatically distribute traffic across multiple destinations within a cluster.

Load Balancing Strategies

YARP supports several load balancing policies:

• PowerOfTwoChoices (default) - picks two random destinations and chooses the one with fewer active requests
• RoundRobin - spreads requests evenly across all destinations in sequence
• Random - randomly selects a destination for each request
• FirstAlphabetical - always picks the first destination alphabetically (useful for testing)
• LeastRequests - routes to the destination with the fewest active requests

Here is how you can configure load balancing for the Shipment Service running on three instances:

json
1{
2  "ReverseProxy": {
3    "Routes": {
4      "products-route": {
5        "ClusterId": "shipments-cluster",
6        "Match": {
7          "Path": "/api/shipments/{**catch-all}"
8        }
9      }
10    },
11    "Clusters": {
12      "shipments-cluster": {
13        "LoadBalancingPolicy": "RoundRobin",
14        "Destinations": {
15          "shipment-service-instance-1": {
16            "Address": "https://localhost:5001/"
17          },
18          "shipment-service-instance-2": {
19            "Address": "https://localhost:5011/"
20          },
21          "shipment-service-instance-3": {
22            "Address": "https://localhost:5012/"
23          }
24        }
25      }
26    }
27  }
28}

With this configuration, YARP distributes requests evenly across all three instances using the Round-Robin strategy.

Health checks let YARP route traffic only to healthy instances. If an instance fails its health check, YARP automatically stops sending requests to it until it recovers.

First, install the health checks package:

bash
1dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks

Configure health checks in appsettings.json:

json
1{
2  "ReverseProxy": {
3    "Routes": {
4      "products-route": {
5        "ClusterId": "shipments-cluster",
6        "Match": {
7          "Path": "/api/shipments/{**catch-all}"
8        }
9      }
10    },
11    "Clusters": {
12      "shipments-cluster": {
13        "LoadBalancingPolicy": "RoundRobin",
14        "HealthCheck": {
15          "Active": {
16            "Enabled": true,
17            "Interval": "00:00:10",
18            "Timeout": "00:00:05",
19            "Policy": "ConsecutiveFailures",
20            "Path": "/health"
21          },
22          "Passive": {
23            "Enabled": true,
24            "Policy": "TransportFailureRate",
25            "ReactivationPeriod": "00:01:00"
26          }
27        },
28        "Destinations": {
29          "shipment-service-instance-1": {
30            "Address": "https://localhost:5001/",
31            "Health": "https://localhost:5001/health"
32          },
33          "shipment-service-instance-2": {
34            "Address": "https://localhost:5011/",
35            "Health": "https://localhost:5011/health"
36          },
37          "shipment-service-instance-3": {
38            "Address": "https://localhost:5012/",
39            "Health": "https://localhost:5012/health"
40          }
41        }
42      }
43    }
44  }
45}

Active Health Checks periodically send requests to the /health endpoint of each destination:

• Interval - how often to check (every 10 seconds)
• Timeout - how long to wait for a response (5 seconds)
• Policy - when to mark a destination as unhealthy (after consecutive failures)
• Path - the health check endpoint on the backend service

Passive Health Checks monitor actual traffic and mark destinations as unhealthy based on real request failures:

• Policy - what triggers marking as unhealthy (transport failures like connection errors)
• ReactivationPeriod - how long to wait before trying an unhealthy destination again (1 minute)

For this to work, your backend services need to expose a health check endpoint. See this article for how to add Health Checks in ASP.NET Core.

Sometimes you need to route requests from the same client to the same backend instance. This is called session affinity or sticky sessions.

For more information, see the following article from official Microsoft documentation.

In a microservices architecture, handling authentication and authorization at the API Gateway level simplifies security management. Instead of implementing authentication in every backend service, you validate tokens once at the gateway and forward authenticated requests to backend services.

This approach provides several benefits:

• Backend services do not need to validate tokens themselves
• You can enforce consistent security policies across all services
• Token validation happens once, reducing overhead
• Backend services receive authenticated user information through headers

JWT Token Validation at Gateway Level

Let's configure YARP to validate JWT tokens before forwarding requests to backend services.

First, install the required NuGet packages:

bash
1dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Configure JWT authentication in Program.cs:

csharp
1using Microsoft.AspNetCore.Authentication.JwtBearer;
2using Microsoft.IdentityModel.Tokens;
3using System.Text;
4
5var builder = WebApplication.CreateBuilder(args);
6
7// Configure JWT authentication
8builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
9    .AddJwtBearer(options =>
10    {
11        options.TokenValidationParameters = new TokenValidationParameters
12        {
13            ValidateIssuer = true,
14            ValidateAudience = true,
15            ValidateLifetime = true,
16            ValidateIssuerSigningKey = true,
17            ValidIssuer = builder.Configuration["Jwt:Issuer"],
18            ValidAudience = builder.Configuration["Jwt:Audience"],
19            IssuerSigningKey = new SymmetricSecurityKey(
20                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]!))
21        };
22    });
23
24builder.Services.AddAuthorization();
25
26builder.Services.AddReverseProxy()
27    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));
28
29var app = builder.Build();
30
31app.UseAuthentication();
32app.UseAuthorization();
33
34app.MapReverseProxy();
35
36app.Run();

Add JWT configuration to appsettings.json:

json
1{
2  "Jwt": {
3    "Key": "YourSuperSecretKeyThatIsAtLeast32CharactersLong",
4    "Issuer": "https://your-auth-server.com",
5    "Audience": "https://your-api-gateway.com"
6  },
7  "ReverseProxy": {
8    "Routes": {
9      "products-route": {
10        "ClusterId": "shipments-cluster",
11        "AuthorizationPolicy": "default",
12        "Match": {
13          "Path": "/api/shipments/{**catch-all}"
14        }
15      },
16      "orders-route": {
17        "ClusterId": "stocks-cluster",
18        "AuthorizationPolicy": "AdminOnly",
19        "Match": {
20          "Path": "/api/stocks/{**catch-all}"
21        }
22      }
23    },
24    "Clusters": {
25      "shipments-cluster": {
26        "Destinations": {
27          "products-service": {
28            "Address": "https://localhost:5001/"
29          }
30        }
31      },
32      "stocks-cluster": {
33        "Destinations": {
34          "orders-service": {
35            "Address": "https://localhost:5002/"
36          }
37        }
38      }
39    }
40  }
41}

The AuthorizationPolicy: "default" setting requires authentication for these routes. Requests without a valid JWT token receive a 401 Unauthorized response.

Another option is AuthorizationPolicy: anonymous. This allows unauthenticated requests to these routes.

You can also configure custom Authorization policies at the gateway level (that we use for stocks-cluster):

csharp
1builder.Services.AddAuthorization(options =>
2{
3    options.AddPolicy("AdminOnly", policy =>
4        policy.RequireRole("Admin"));
5});

Path rewriting allows you to transform incoming request URLs before forwarding them to backend services.

This is useful when:

• Your public API structure differs from your internal service structure
• You need to support multiple API versions
• You want to expose different endpoints to different clients (A/B testing)

YARP provides transformation capabilities that let you modify paths, query strings, and headers.

Let's explore an example where you can route different API versions to different backend services or different endpoints:

json
1{
2  "ReverseProxy": {
3    "Routes": {
4      "products-v1-route": {
5        "ClusterId": "products-v1-cluster",
6        "Match": {
7          "Path": "/api/v1/products/{**remainder}"
8        }
9      },
10      "products-v2-route": {
11        "ClusterId": "products-v2-cluster",
12        "Match": {
13          "Path": "/api/v2/products/{**remainder}"
14        },
15        "Transforms": [
16          {
17            "PathPattern": "/api/shipments/{**remainder}"
18          }
19        ]
20      }
21    },
22    "Clusters": {
23      "products-v1-cluster": {
24        "Destinations": {
25          "products-v1-service": {
26            "Address": "https://localhost:5001/"
27          }
28        }
29      },
30      "products-v2-cluster": {
31        "Destinations": {
32          "products-v2-service": {
33            "Address": "https://localhost:5002/"
34          }
35        }
36      }
37    }
38  }
39}

This configuration:

• Routes /api/v1/products/* to the v1 service without path transformation
• Routes /api/v2/products/* to the v2 service and removes the version prefix

You can explore more examples in the official documentation.

The Backend-For-Frontend pattern creates specialized API gateways for different client types. Mobile apps, web applications, and third-party integrations often need different data formats, aggregation levels, and performance characteristics.

Instead of forcing all clients to use the same API, you create tailored endpoints that serve each client's specific needs.

Why Use BFF Pattern:

• Mobile apps need smaller payloads and fewer round trips
• Web applications can handle larger responses and more complex data
• Different clients need different authentication mechanisms
• You can optimize responses for each platform without affecting others

Here is how you can configure YARP to route requests to different backend services based on the client type:

json
1{
2  "ReverseProxy": {
3    "Routes": {
4      "mobile-products-route": {
5        "ClusterId": "mobile-bff-cluster",
6        "Match": {
7          "Path": "/api/shipments/{**remainder}",
8          "Headers": [
9            {
10              "Name": "X-Client-Type",
11              "Values": ["mobile"],
12              "Mode": "ExactHeader"
13            }
14          ]
15        }
16      },
17      "web-products-route": {
18        "ClusterId": "web-bff-cluster",
19        "Match": {
20          "Path": "/api/shipments/{**remainder}",
21          "Headers": [
22            {
23              "Name": "X-Client-Type",
24              "Values": ["web"],
25              "Mode": "ExactHeader"
26            }
27          ]
28        }
29      },
30      "default-products-route": {
31        "ClusterId": "web-bff-cluster",
32        "Match": {
33          "Path": "/api/shipments/{**remainder}"
34        }
35      }
36    },
37    "Clusters": {
38      "mobile-bff-cluster": {
39        "Destinations": {
40          "mobile-bff-service": {
41            "Address": "https://localhost:5001/"
42          }
43        }
44      },
45      "web-bff-cluster": {
46        "Destinations": {
47          "web-bff-service": {
48            "Address": "https://localhost:5002/"
49          }
50        }
51      }
52    }
53  }
54}

Mobile clients send X-Client-Type: mobile header and get routed to the mobile BFF service, which returns optimized, smaller payloads. Web clients get routed to the web BFF service with richer data.

Rate limiting protects your backend services from being overwhelmed by too many requests. Without rate limiting, a single client can consume all available resources, causing service degradation or outages for other users.

YARP does not include built-in rate limiting, but you can integrate ASP.NET Core's rate limiting middleware to control traffic at the gateway level.

ASP.NET Core 7.0 and later includes built-in rate limiting middleware.

Let's explore a simple Fixed window rate limiting that allows a specific number of requests within a time window:

csharp
1using System.Threading.RateLimiting;
2
3var builder = WebApplication.CreateBuilder(args);
4
5builder.Services.AddRateLimiter(options =>
6{
7    options.AddFixedWindowLimiter("fixed", limiterOptions =>
8    {
9        limiterOptions.PermitLimit = 100;
10        limiterOptions.Window = TimeSpan.FromMinutes(1);
11        limiterOptions.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
12        limiterOptions.QueueLimit = 10;
13    });
14});
15
16builder.Services.AddReverseProxy()
17    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));
18
19var app = builder.Build();
20
21app.UseRateLimiter();
22app.MapReverseProxy();
23
24app.Run();

Apply rate limiting to specific routes in appsettings.json:

json
1{
2  "ReverseProxy": {
3    "Routes": {
4      "products-route": {
5        "ClusterId": "shipments-cluster",
6        "RateLimiterPolicy": "fixed",
7        "Match": {
8          "Path": "/api/shipments/{**catch-all}"
9        }
10      }
11    },
12    "Clusters": {
13      "shipments-cluster": {
14        "Destinations": {
15          "products-service": {
16            "Address": "https://localhost:5001/"
17          }
18        }
19      }
20    }
21  }
22}

This configuration allows 100 requests per minute per client. When the limit is exceeded, requests are queued (up to 10), and additional requests receive a 429 Too Many Requests response.

Explore more rate limiting options in the official documentation.

Observability is essential for understanding what happens inside your API Gateway. Without proper logging and tracing, debugging issues in a distributed system becomes pretty hard.

YARP integrates seamlessly with ASP.NET Core's logging infrastructure and OpenTelemetry for distributed tracing.

For structured logging, install Serilog:

bash
1dotnet add package Serilog.AspNetCore
2dotnet add package Serilog.Sinks.Seq

And register Serilog in Program.cs:

csharp
1builder.Host.UseSerilog((context, loggerConfig) => 
2    loggerConfig.ReadFrom.Configuration(context.Configuration));

See a full example of how to configure Serilog logging here.

OpenTelemetry provides distributed tracing, metrics, and logs. Install the required packages:

bash
1dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
2dotnet add package OpenTelemetry.Extensions.Hosting
3dotnet add package OpenTelemetry.Instrumentation.AspNetCore
4dotnet add package OpenTelemetry.Instrumentation.Http
5dotnet add package OpenTelemetry.Instrumentation.Runtime

Configure OpenTelemetry in Program.cs:

csharp
1builder.Services
2 .AddOpenTelemetry()
3 .ConfigureResource(resource => resource.AddService("shipping-gateway"))
4 .WithTracing(tracing =>
5 {
6  tracing
7   .AddAspNetCoreInstrumentation()
8   .AddHttpClientInstrumentation()
9   .AddSource("Yarp.ReverseProxy");
10
11  tracing.AddOtlpExporter();
12 });

Configure middlewares to use Serilog HTTP request and response logging, YARP timeout handling and reverse proxy:

csharp
1var app = builder.Build();
2
3app.UseMiddleware<LogContextTraceLoggingMiddleware>();
4
5app.UseSerilogRequestLogging();
6
7app.UseRequestTimeouts();
8
9app.MapReverseProxy();
10
11await app.RunAsync();

Add trace ID to track requests across services:

csharp
1internal sealed class LogContextTraceLoggingMiddleware(RequestDelegate next)
2{
3    public async Task Invoke(HttpContext context)
4    {
5        var traceId = Activity.Current?.TraceId.ToString();
6
7        using (LogContext.PushProperty("TraceId", traceId))
8        {
9            await next.Invoke(context);
10        }
11    }
12}
13
14app.UseMiddleware<LogContextTraceLoggingMiddleware>();
15
16app.UseSerilogRequestLogging();
17
18app.UseRequestTimeouts();
19
20app.MapReverseProxy();

Beyond the core scenarios we explored, YARP supports several advanced patterns that help with system evolution and deployment strategies.

Gradual Migration from Monolith to Microservices

When migrating from a monolith to microservices, you cannot rewrite everything at once. YARP helps you migrate gradually by routing some endpoints to the new microservices while keeping others in the monolith.

You can configure routes to split traffic between monoliths and microservices.

Canary Releases and Gradual Rollouts

Canary releases let you deploy new versions to a small percentage of users before rolling out to everyone. This reduces the risk of introducing bugs.

You can configure weighted routing to split traffic between versions with "LoadBalancingPolicy": "Random"

For example, with 5 total destinations (4 running v1, 1 running v2), approximately 20% of traffic goes to the new version. Monitor error rates and performance. If everything looks good, gradually increase the percentage by adding more v2 instances and removing v1 instances.

A/B Testing

You can use the same load balancing approach to implement A/B testing.

Or you can implement a more advanced header-based traffic distribution for more control:

csharp
1builder.Services.AddReverseProxy()
2    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"))
3    .AddTransforms(context =>
4    {
5        context.AddRequestTransform(async transformContext =>
6        {
7            var httpContext = transformContext.HttpContext;
8            var userId = httpContext.User.FindFirst("sub")?.Value;
9            
10            // Route 10% of users to a new service based on user ID hash
11            if (!string.IsNullOrEmpty(userId))
12            {
13                var hash = Math.Abs(userId.GetHashCode());
14                var isCanaryUser = (hash % 100) < 10;
15                
16                if (isCanaryUser)
17                {
18                    transformContext.ProxyRequest.Headers.Add("X-New-Service-User", "true");
19                }
20            }
21            
22            await Task.CompletedTask;
23        });
24    });

These patterns make YARP a powerful tool not just for routing traffic, but for managing the entire lifecycle of your distributed system.

YARP provides a flexible and powerful foundation for building API Gateways in .NET. Unlike traditional API Gateway solutions with fixed features, YARP provides building blocks you can compose and extend to create exactly the gateway you need.

YARP integrates seamlessly with the ASP.NET Core ecosystem, giving you access to authentication, authorization, logging, health checks, and all other middleware. You can extend it with custom transforms, policies, and middleware to handle any scenario.

Whether you are building a new microservices architecture, migrating from a monolith, or creating specialized gateways for different clients, YARP provides the flexibility and performance you need.

Hope you find this newsletter useful. See you next time.