Building an API gateway with YARP and .NET 8

Modern applications rarely expose every service directly to clients. A browser, mobile app or partner integration usually needs one reliable entry point that can route requests, apply security policies, standardise responses and protect internal services. For teams building on ASP.NET Core, YARP provides a practical way to create that reverse proxy without introducing a separate gateway product.

YARP, or Yet Another Reverse Proxy, is a .NET library developed by Microsoft. Combined with .NET 8, it supports a flexible API gateway architecture with route matching, load balancing, health checks, transforms and middleware. This approach suits Australian development teams managing cloud workloads in Sydney or Melbourne, where latency, data residency and operational simplicity can influence gateway design.

Why an API gateway belongs at the edge

An API gateway sits between external consumers and internal services. Instead of publishing separate endpoints for orders, accounts, payments and notifications, a client can call a consistent public host. The gateway forwards each request to the appropriate backend while keeping internal hostnames, ports and deployment details private.

This boundary is useful for more than routing. Authentication, request correlation, rate limiting, header normalisation, CORS, TLS termination and access logging can be handled centrally. A gateway can also shield older services from public exposure while a platform team gradually modernises them.

YARP is especially attractive when the delivery team already uses C#, ASP.NET Core dependency injection, Microsoft Entra ID and Azure. Developers can extend the proxy with normal .NET middleware and services rather than learning a separate scripting language. It remains important to keep the gateway focused: business rules and domain workflows belong in application services, not in route configuration.

For an Australian service, deployment location deserves early attention. Hosting the gateway and primary APIs in an Australian Azure region can reduce round-trip time for users in Sydney, Brisbane and Melbourne. It may also support contractual or regulatory expectations around where customer information is processed, although the gateway itself does not automatically guarantee compliance with the Privacy Act or Australian Privacy Principles.

Creating the .NET 8 gateway project

Start with a standard ASP.NET Core application and add the YARP package:

dotnet new web -n Gateway
cd Gateway
dotnet add package Yarp.ReverseProxy

A minimal Program.cs can load routes and clusters from configuration:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

app.UseHttpsRedirection();
app.MapReverseProxy();

app.Run();

The AddReverseProxy call registers YARP services, while LoadFromConfig reads the routing model from appsettings.json. MapReverseProxy adds the endpoint that receives matching requests and forwards them to a destination.

A basic configuration might look like this:

{
  "ReverseProxy": {
    "Routes": {
      "catalog-route": {
        "ClusterId": "catalog-cluster",
        "Match": {
          "Path": "/api/catalog/{**catch-all}"
        }
      }
    },
    "Clusters": {
      "catalog-cluster": {
        "Destinations": {
          "catalog-service": {
            "Address": "https://localhost:7001/"
          }
        }
      }
    }
  }
}

The route defines the public path, and the cluster defines one or more backend destinations. In a production environment, destination addresses should normally come from environment-specific configuration, service discovery or a managed platform rather than being hard-coded into source control.

Designing routes, clusters and transforms

YARP separates route matching from destination selection. This distinction makes the gateway easier to evolve. A route can match a path, HTTP method, host or header, while a cluster can contain several destinations and a load-balancing policy. Multiple public routes may therefore share the same backend cluster.

Path transforms are useful when public and internal URL structures differ. For example, clients might call /api/orders/123, while an internal service expects /orders/123. A transform can remove or add a path prefix before forwarding the request. Header transforms can add correlation identifiers, preserve the original host or remove headers that should never reach an internal service.

A route with a transform could be configured as follows:

{
  "Routes": {
    "orders-route": {
      "ClusterId": "orders-cluster",
      "Match": {
        "Path": "/api/orders/{**remainder}"
      },
      "Transforms": [
        { "PathRemovePrefix": "/api" },
        { "RequestHeader": "X-Gateway", "Set": "yarp" }
      ]
    }
  }
}

Use explicit route conventions. Keep public versioning such as /api/v1 stable, and avoid exposing internal service names in client-facing URLs. In a multi-team environment, consistent naming helps developers in Melbourne or Perth understand ownership when they inspect logs and deployment settings.

YARP also supports health checks and load balancing. A cluster can contain several instances of a service, allowing traffic to be distributed across containers, virtual machines or App Service deployments. Health monitoring should reflect actual service readiness rather than simply confirming that a process is running.

Adding authentication, authorisation and resilience

Authentication should be enforced at the correct boundary. A gateway can validate bearer tokens issued by Microsoft Entra ID or another identity provider before forwarding requests. ASP.NET Core authentication and authorisation middleware can protect all routes or selected route groups.

A typical setup registers JWT bearer authentication:

builder.Services.AddAuthentication("Bearer")
    .AddJwtBearer("Bearer", options =>
    {
        options.Authority = builder.Configuration["Identity:Authority"];
        options.Audience = "api";
    });

builder.Services.AddAuthorization();

var app = builder.Build();

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

The exact order and policy design should match the application’s security model. Some systems pass the original token to downstream services so each service can perform its own authorisation. Others exchange the external token for a narrower internal credential. Avoid treating authentication at the gateway as a substitute for service-level authorisation.

Resilience features require equal care. Timeouts prevent a slow dependency from consuming every gateway thread, while retries can help with short-lived network faults. Retrying non-idempotent operations such as payments or order creation can create duplicate actions, so retry policies should consider the HTTP method and business semantics.

Useful gateway controls include:

• Request timeouts and cancellation propagation
• Rate limits for public and partner-facing endpoints
• Circuit breakers for failing downstream services
• Maximum request and response sizes

For Australian consumer traffic, rate limiting can help absorb sudden demand from a campaign, sporting event or retail promotion. It should be paired with clear client responses such as HTTP 429 and useful retry guidance rather than silently dropping requests.

Observability and production operations

A gateway becomes a central diagnostic point, so its telemetry must be designed before launch. Record structured logs with a correlation ID, route name, destination, status code, duration and failure category. Do not log access tokens, passwords, payment details or unnecessary personal information.

OpenTelemetry integrates well with modern .NET applications and can export traces and metrics to Azure Monitor, Application Insights or another observability platform. Distributed tracing allows an engineer to follow a request from the gateway to an orders service, database and external provider. This is far more useful than a single “502 Bad Gateway” message.

Health endpoints should distinguish between process health and dependency readiness. A liveness check can confirm that the gateway is running, while a readiness check can indicate whether it can safely accept traffic. Kubernetes, Azure Container Apps and other hosting platforms use these signals to make deployment decisions.

Operational checks worth defining include:

• Gateway latency by route and HTTP status
• Upstream failures, timeouts and connection errors
• Requests rejected by authentication or rate limits
• Destination health and load distribution

In Australia, teams should verify that monitoring data is stored in an approved region and that retention settings match organisational policy. A company serving customers across New South Wales and Victoria may also need alert coverage outside standard office hours, especially when the gateway fronts payments, logistics or public-sector services.

Securing configuration and deployment

Configuration should be externalised across development, testing and production. Local developers can use user secrets or a development settings file, while production deployments can use Azure App Configuration, Key Vault, managed identities or environment variables. Never place client secrets, certificates or database credentials in appsettings.json committed to a repository.

TLS should terminate at a trusted edge such as Azure Front Door, Application Gateway or the hosting platform, depending on the network design. Encrypting the connection from the edge to YARP and from YARP to internal services provides stronger protection across the entire path. Internal services should still validate identity and apply their own authorisation rules.

A production pipeline should build, test and scan the gateway as an ordinary .NET 8 application. Include route tests, authentication tests, transform tests and failure scenarios. Contract tests can confirm that the gateway continues to produce the paths and headers expected by downstream services.

Blue-green or rolling deployments reduce risk when changing routes. A new route should first target a test destination or limited audience. Logs and metrics can then confirm that forwarding, latency and authentication behave as expected before traffic is expanded. This staged approach is valuable for teams supporting customers across Australian time zones, where a fault introduced during a late Sydney deployment may affect users nationwide.

Extending YARP without creating a bottleneck

YARP can be extended through custom transforms, destination resolvers, load-balancing policies and proxy middleware. These extension points are powerful, but every custom feature increases the gateway’s maintenance surface. Prefer built-in configuration where it expresses the requirement clearly, and add code only when a reusable policy cannot be configured.

A custom transform may add tenant context, rewrite a header or adapt a legacy backend. It should validate input and avoid trusting client-supplied identity headers. If a downstream service needs a tenant identifier, derive it from a verified token or trusted server-side lookup rather than accepting arbitrary values from the request.

The gateway should remain stateless wherever possible. Stateless instances can scale horizontally behind a load balancer and can be replaced during deployments without session migration. Shared state, such as throttling counters or temporary tokens, should be managed by a dedicated service with clear availability characteristics.

Before releasing a YARP gateway, check these implementation details:

• Confirm every public route has an authentication and authorisation policy
• Test unhealthy destinations and slow downstream responses
• Verify forwarded headers and original client IP handling
• Review sensitive data in logs, traces and error responses

A well-designed .NET 8 gateway gives developers a controlled edge for APIs while preserving the freedom to evolve internal services. YARP is most effective when paired with disciplined route ownership, secure configuration, meaningful telemetry and realistic load testing. That combination supports a maintainable platform for cloud-native applications, whether the workload serves a local Australian business or a distributed global customer base.