YARP vs Ocelot for .NET API Gateways

YARP and Ocelot both help .NET teams put a gateway or reverse proxy in front of downstream services.

They do not feel the same in production.

YARP feels like a programmable ASP.NET Core reverse proxy framework. Ocelot feels like a .NET API gateway product that is configured around routes, downstream services, authentication, rate limiting, aggregation, and resilience options.

That difference matters more than most feature checklists.

If your team asks "YARP vs Ocelot," the real question is:

Do we want to build gateway behavior as ASP.NET Core code, or configure gateway behavior as an API gateway?

This guide compares YARP and Ocelot for .NET teams in 2026, with a focus on routing, authentication, rate limiting, transforms, performance, operational ownership, and migration fit.

Executive Summary

Choose YARP when your team wants:

• deep ASP.NET Core integration
• high control over middleware and routing
• custom transforms
• strong performance orientation
• flexible load balancing and health behavior
• a gateway that feels like application code
• developers who are comfortable owning custom proxy behavior

Choose Ocelot when your team wants:

• a configuration-driven .NET API gateway
• route mapping in gateway config
• built-in gateway concepts
• easier setup for common gateway needs
• route-level authentication and authorization options
• built-in aggregation patterns
• quality-of-service configuration through Polly
• a simpler model for smaller .NET microservice systems

The short version:

If you are deciding between Ocelot, YARP, and Kong, read the broader API Gateway Comparison 2026: Ocelot vs YARP vs Kong. This article stays focused on the .NET-native decision.

What YARP is best at

Microsoft's YARP overview describes YARP as a highly customizable reverse proxy library for .NET. That phrase is the key: library, not boxed gateway platform.

YARP is strongest when the gateway should live inside the normal ASP.NET Core programming model.

That means you can use:

• ASP.NET Core middleware
• endpoint routing
• authentication and authorization middleware
• dependency injection
• configuration providers
• logging and telemetry
• custom transforms
• route and cluster configuration
• load balancing
• health checks
• session affinity

The YARP getting started documentation shows the basic shape:

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

app.MapReverseProxy();

That is intentionally small. YARP gives you the proxy layer and lets your ASP.NET Core app supply the surrounding gateway behavior.

What Ocelot is best at

Ocelot is a .NET API gateway built around gateway configuration.

Its routing documentation describes a route as the process of handling an incoming HTTP request and forwarding it to a downstream service. A typical route maps an upstream path and method to a downstream path, scheme, host, and port.

The configuration-first style is the appeal:

{
  "Routes": [
    {
      "UpstreamHttpMethod": [ "Get" ],
      "UpstreamPathTemplate": "/orders/{id}",
      "DownstreamPathTemplate": "/api/orders/{id}",
      "DownstreamScheme": "https",
      "DownstreamHostAndPorts": [
        { "Host": "orders-api", "Port": 443 }
      ]
    }
  ]
}

That is easier for many teams to reason about than custom reverse-proxy code, especially when the gateway needs to stay close to a declarative operations model.

Ocelot is strongest when your gateway needs common API gateway features without becoming a large custom application.

Routing comparison

Routing is where the two tools first feel different.

YARP routing

YARP uses route and cluster configuration. A route matches incoming requests. A cluster defines destinations. YARP can load configuration from ASP.NET Core configuration providers, and the configuration documentation explains how routes and clusters can be loaded from files through IConfiguration.

YARP routing is a good fit when:

• routing should be part of application configuration
• routes need custom matching behavior
• you want to combine proxy routing with ASP.NET Core endpoints
• you want route behavior to evolve in code
• you need custom transforms or middleware around routing

Ocelot routing

Ocelot routing is more explicitly gateway-shaped. It maps upstream requests to downstream services through route configuration. Ocelot also gives you concepts such as downstream host and port collections, route keys, service discovery, and route-level options.

Ocelot routing is a good fit when:

• the gateway is mostly route mapping
• the team wants a dedicated gateway config file
• route behavior should be visible without reading C# middleware
• common gateway controls are configured per route
• a small platform team owns gateway changes

Authentication and authorization

Both tools can support authentication, but they differ in how much they package.

YARP authentication

YARP sits naturally inside ASP.NET Core. You typically use ASP.NET Core authentication and authorization middleware around proxied routes.

That is powerful because your gateway can share the same auth stack as other ASP.NET Core apps:

• JWT bearer authentication
• OpenID Connect
• policy-based authorization
• claims transformation
• custom middleware
• route-specific policies

This is one of YARP's strengths. It does not invent a separate auth model; it lets you use the normal ASP.NET Core model.

The trade-off is that your team must design that model.

Ocelot authentication

Ocelot's authentication documentation describes registering authentication services in the application and mapping schemes to routes through AuthenticationOptions. It also supports allowed scopes for route access after authentication.

This is attractive when you want route-level gateway configuration to express auth behavior clearly.

Ocelot is easier when:

• auth decisions are route-based
• the config should show which route uses which scheme
• scope checks belong near route configuration
• the gateway team wants fewer custom auth components

YARP is easier when:

• auth behavior is code-heavy
• policies are complex
• existing ASP.NET Core authorization is already mature
• downstream headers and claims need custom transformation

Rate limiting

Rate limiting is another place where the tools reveal their philosophy.

Ocelot has its own rate limiting feature. The current Ocelot rate limiting documentation notes that its own middleware supports and processes the "By Client's Header" rule, commonly referred to as an API-key partition in ASP.NET Core terminology.

That is useful for gateway-style configuration, but it also means you should understand the limits of the built-in model.

YARP does not try to be a packaged rate limiting product. You typically combine it with ASP.NET Core rate limiting middleware or custom logic.

Choose Ocelot for rate limiting when:

• basic route-level client-header rate limiting is enough
• config-driven behavior matters
• the gateway should stay simple

Choose YARP for rate limiting when:

• you need custom partition keys
• you want token bucket, fixed window, sliding window, or concurrency policies in code
• you need rate limiting tied to identity, route metadata, tenant, plan, or downstream cost
• you already use ASP.NET Core rate limiting elsewhere

If your rate limiting strategy is sophisticated, YARP often fits better because you are probably writing policy code anyway.

Transforms and request shaping

YARP is very strong when you need custom request and response transforms.

Common examples:

• add or remove headers
• rewrite paths
• normalize forwarded headers
• map claims into downstream headers
• short-circuit certain requests
• add diagnostic headers
• apply tenant-specific routing decisions

YARP is designed to be extended inside the request pipeline.

Ocelot also supports request shaping through gateway configuration and features such as claims-to-headers, downstream route options, and aggregation. But if the gateway behavior becomes deeply custom, teams often start pushing Ocelot beyond its easiest shape.

The practical line:

• If the behavior is mostly route configuration, Ocelot is pleasant.
• If the behavior is mostly custom HTTP pipeline logic, YARP is usually cleaner.

Aggregation and composition

Ocelot has a direct request aggregation story. Its aggregation documentation describes basic and advanced aggregation patterns where multiple downstream requests can be combined.

That can be useful for backend-for-frontend style gateway composition.

YARP is not primarily an aggregation framework. You can build composition around it with ASP.NET Core endpoints, services, and custom code, but you are designing the behavior yourself.

Choose Ocelot when:

• you want gateway-level aggregation as a packaged feature
• the aggregation logic is simple or moderate
• gateway config should describe the composition

Choose YARP when:

• aggregation logic is business-specific
• composition needs custom service code
• the behavior belongs in a BFF endpoint rather than proxy config

Resilience and quality of service

Ocelot includes quality-of-service options through Polly integration. The current Ocelot QoS documentation describes per-route circuit breaker and timeout behavior through Ocelot.Provider.Polly.

That is a strong convenience for gateway teams that want route-level resilience controls.

YARP gives you a lower-level proxy foundation. You can design resilience with:

• ASP.NET Core middleware
• timeout policies
• health checks
• load balancing behavior
• custom delegating handlers
• downstream service policies
• OpenTelemetry instrumentation

Again, the pattern is consistent:

• Ocelot packages more gateway behavior.
• YARP gives more framework-level control.

Performance and maintenance

YARP is usually the stronger choice when raw proxy performance and low-level control are major criteria. It is built by Microsoft, integrates tightly with ASP.NET Core, and is actively maintained as part of the modern .NET ecosystem.

But performance is not the only operational question.

Ask:

• Who will own this gateway?
• Is the team stronger in C# middleware or gateway configuration?
• How often do routes change?
• Do developers or operators own route changes?
• How much custom behavior is expected?
• Does the gateway need to be boring or deeply programmable?
• How much testing will custom gateway code require?

Ocelot can be easier to operate when the gateway mostly changes through configuration.

YARP can be easier to operate when the gateway is a real ASP.NET Core application with custom behavior, tests, and normal code ownership.

Migration: Ocelot to YARP

Many teams consider moving from Ocelot to YARP when:

• gateway logic has become code-heavy
• performance concerns are increasing
• ASP.NET Core middleware integration matters more
• route config is no longer enough
• custom auth or transforms dominate the gateway
• the team wants more control over HTTP behavior

But migration is not automatic.

You must map:

• Ocelot routes to YARP routes and clusters
• Ocelot auth options to ASP.NET Core auth policies
• Ocelot rate limiting to ASP.NET Core rate limiting
• Ocelot aggregation to BFF endpoints or custom services
• Ocelot QoS options to middleware, handlers, or downstream policies
• Ocelot service discovery to YARP config providers or custom resolution

The safest migration path is usually route-by-route:

1. Inventory current Ocelot features by route.
2. Identify routes that are pure proxying.
3. Move pure proxy routes first.
4. Recreate authentication and headers carefully.
5. Leave aggregation or custom gateway behavior for later.
6. Compare logs, status codes, and downstream headers before switching traffic.

Migration: YARP to Ocelot

Moving from YARP to Ocelot is less common, but it can make sense when:

• the gateway became too custom
• route changes should be easier for non-developers
• the team wants a more declarative gateway model
• built-in Ocelot gateway features cover most needs
• custom code has become a maintenance burden

This migration is about reducing flexibility on purpose.

If the team does not need custom middleware and wants a simpler config-driven gateway, Ocelot may be the healthier long-term choice.

Decision checklist

Choose YARP if most of these are true:

• Your team is strong in ASP.NET Core.
• You need custom middleware.
• You need custom transforms.
• You care deeply about proxy performance.
• You want to compose gateway behavior in C#.
• You already have auth policies in ASP.NET Core.
• Your gateway is part of a larger .NET platform.
• You are comfortable building missing gateway features yourself.

Choose Ocelot if most of these are true:

• You want a .NET API gateway with built-in gateway concepts.
• Your routes are mostly straightforward.
• Gateway config should be easy to inspect.
• Route-level authentication and scopes are enough.
• Basic rate limiting works for your needs.
• You want built-in aggregation options.
• You want Polly-based QoS options in gateway config.
• Your team prefers gateway configuration over custom proxy code.

Evaluate another gateway or API management platform if:

• you need a developer portal
• you need API products or subscriptions
• you need enterprise API governance
• you need multi-language platform ownership
• you need advanced plugin ecosystems
• you need global edge policy controls
• you need monetization, quotas, analytics, and lifecycle controls

YARP and Ocelot are excellent .NET-native choices, but they are not full enterprise API management platforms by themselves.

Common mistakes

Mistake 1: choosing by performance alone

Performance matters, but team fit matters too. A high-performance proxy that nobody can maintain becomes a platform risk.

Mistake 2: assuming Ocelot is only for old systems

Ocelot is still useful when gateway configuration is the right operating model. Not every .NET team needs a fully programmable reverse proxy.

Mistake 3: assuming YARP is a drop-in Ocelot replacement

YARP can replace Ocelot in some systems, but you must recreate the Ocelot features you depend on. Routing is only one part of a gateway.

Mistake 4: putting business authorization in the gateway

Gateways are good at authentication, coarse route policy, token validation, headers, and traffic controls. Fine-grained business authorization usually belongs in the downstream service that understands the resource.

Mistake 5: forgetting observability

Whichever tool you choose, instrument:

• route match
• downstream destination
• status code
• latency
• retries or failures
• auth outcome
• rate limit outcome
• correlation IDs

The OpenTelemetry Config Generator can help sketch the observability side of a gateway rollout.

Final recommendation

For many .NET teams in 2026:

• YARP is the better long-term technical foundation when the gateway is a programmable ASP.NET Core reverse proxy.
• Ocelot is the better starting point when the gateway should stay configuration-driven and cover common API gateway needs quickly.

If you are a small .NET team with straightforward microservices, Ocelot can still be the faster, clearer path.

If you are a platform team building a custom edge layer in ASP.NET Core, YARP will usually age better.

The deciding question is not "which one has more features?"

The deciding question is:

Do we want to own gateway behavior as code or as gateway configuration?

FAQ

Is YARP better than Ocelot?

YARP is better when you need a highly programmable ASP.NET Core reverse proxy with custom middleware, transforms, and deep code-level control. Ocelot is better when you want a configuration-driven .NET API gateway with packaged gateway features.

Is Ocelot still worth using for .NET API gateways?

Yes. Ocelot remains useful for teams that want route configuration, authentication options, service discovery, aggregation, rate limiting, and Polly-backed quality-of-service behavior without building every piece from scratch.

When should I choose YARP over Ocelot?

Choose YARP when your gateway needs custom behavior, strong ASP.NET Core integration, performance-oriented proxying, custom transforms, or advanced policies that are easier to express in C# than gateway JSON.

When should I choose Ocelot over YARP?

Choose Ocelot when your gateway mostly needs clear route mapping, route-level authentication, basic rate limiting, aggregation, resilience settings, and configuration that a small .NET team can understand quickly.

Can YARP replace Ocelot?

Sometimes. YARP can replace Ocelot when your team is prepared to rebuild any Ocelot-specific behavior it uses, such as aggregation, route-level options, rate limiting, QoS, and auth configuration. Treat it as a migration, not a package swap.

References

• Microsoft Learn: Overview of YARP
• Microsoft Learn: Getting Started with YARP
• Microsoft Learn: YARP configuration files
• Microsoft Learn: YARP middleware
• Ocelot Gateway: Routing
• Ocelot Gateway: Authentication
• Ocelot Gateway: Rate Limiting
• Ocelot Gateway: Quality of Service