Ocelot — Lightweight API Gateway for .NET

Introduction

Ocelot is a .NET API gateway designed for microservice architectures. It sits in front of your services and handles cross-cutting concerns like routing, authentication, rate limiting, and load balancing, all configured through a JSON file without requiring external infrastructure like NGINX or Envoy.

What Ocelot Does

• Routes incoming HTTP requests to downstream services based on URL patterns
• Supports request aggregation to combine multiple service calls into one response
• Provides rate limiting and quality-of-service controls per route
• Integrates with .NET authentication middleware (JWT, OAuth, IdentityServer)
• Handles load balancing across multiple downstream instances

Architecture Overview

Ocelot runs as ASP.NET Core middleware in a standard .NET web application. It reads route definitions from ocelot.json at startup and builds a pipeline of delegating handlers for each route. Middleware components for authentication, authorization, rate limiting, and caching execute in order for each request before forwarding to the downstream service.

Self-Hosting & Configuration

• Install the Ocelot NuGet package into an ASP.NET Core project
• Define routes in ocelot.json with upstream and downstream path templates
• Register Ocelot in Program.cs: builder.Services.AddOcelot(); app.UseOcelot().Wait();
• Enable service discovery with Consul or Eureka by adding the corresponding Ocelot package
• Configure caching with Ocelot.Cache.CacheManager for response caching

Key Features

• JSON-based configuration with no external gateway infrastructure needed
• Built-in support for Consul and Eureka service discovery
• Request aggregation reduces chattiness between client and microservices
• Middleware pipeline integrates with standard ASP.NET Core auth and logging
• Supports WebSocket proxying and header transformation

Comparison with Similar Tools

• YARP — Microsoft's reverse proxy library; lower-level and more flexible but requires more code
• Kong — full-featured gateway with plugins; Ocelot is lighter and .NET-native
• Envoy — high-performance C++ proxy; Ocelot is simpler for .NET teams who want in-process control
• Traefik — auto-discovers services via Docker labels; Ocelot uses JSON config or service registries
• Azure API Management — managed cloud service; Ocelot is self-hosted and free

FAQ

Q: Is Ocelot suitable for production use? A: Yes. Ocelot is used in production .NET microservice deployments and supports horizontal scaling behind a load balancer.

Q: Can Ocelot handle authentication? A: Yes. It integrates with ASP.NET Core authentication middleware, supporting JWT bearer tokens, OAuth 2.0, and IdentityServer.

Q: Does Ocelot support gRPC? A: Ocelot primarily handles HTTP traffic. For gRPC, teams typically use Envoy or YARP as the proxy layer.

Q: How do I update routes without restarting? A: Ocelot supports dynamic configuration reloading and integration with Consul for real-time route updates.

Sources

• https://github.com/ThreeMammals/Ocelot
• https://ocelot.readthedocs.io/