# Ocelot — Lightweight API Gateway for .NET

> A .NET API gateway that handles routing, authentication, rate limiting, and load balancing for microservice architectures. Configure everything in a single JSON file with no external infrastructure.

## Install

Save in your project root:

# Ocelot — Lightweight API Gateway for .NET

## Quick Use
```bash
dotnet new webapi -n MyGateway
cd MyGateway
dotnet add package Ocelot
```
```json
// ocelot.json
{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/{everything}",
      "DownstreamScheme": "https",
      "DownstreamHostAndPorts": [{ "Host": "localhost", "Port": 5001 }],
      "UpstreamPathTemplate": "/svc/{everything}",
      "UpstreamHttpMethod": ["Get"]
    }
  ],
  "GlobalConfiguration": { "BaseUrl": "https://localhost:5000" }
}
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-28cd00d1
Author: AI Open Source