Ocelot
.NET API Gateway
Install / Use
/learn @ThreeMammals/OcelotREADME
About
Ocelot is a .NET API gateway. This project is aimed at people using .NET running a microservices (service-oriented) architecture that needs a unified point of entry into their system. However, it will work with anything that speaks HTTP(S) and runs on any platform that ASP.NET Core supports.
<!-- In particular we want easy integration with [IdentityServer](https://github.com/IdentityServer) reference and [Bearer](https://oauth.net/2/bearer-tokens/) tokens. We have been unable to find this in our current workplace without having to write our own Javascript middlewares to handle the IdentityServer reference tokens. We would rather use the IdentityServer code that already exists to do this. -->Ocelot consists of a series of ASP.NET Core middlewares arranged in a specific order.
Ocelot custom middlewares manipulate the HttpRequest object into a state specified by its configuration until it reaches a request builder middleware, where it creates a HttpRequestMessage object, which is used to make a request to a downstream service.
The middleware that makes the request is the last thing in the Ocelot pipeline. It does not call the next middleware.
The response from the downstream service is retrieved as the request goes back up the Ocelot pipeline.
There is a piece of middleware that maps the HttpResponseMessage onto the HttpResponse object, and that is returned to the client.
That is basically it, with a bunch of other features!
Install
Ocelot is designed to work with ASP.NET Core and it targets net9.0 STS and net8.0, net10.0 LTS target framework monikers (TFMs). [^1]
Install Ocelot package and its dependencies using NuGet package manager:
Install-Package Ocelot
Or via the .NET CLI:
dotnet add package Ocelot
All versions are available on NuGet.
Documentation
- RST-sources: This includes the source code for the documentation (in reStructuredText format, .rst files), which is up to date for the current development. And the rendered HTML documentation is available here.
- Read the Docs: This official website, in HTML format, contains a wealth of information and will be helpful if you want to understand the features that Ocelot currently offers. The rendered HTML documentation, which is currently in development, is available here.
- Ask Ocelot Guru: It is an AI focused on Ocelot, designed to answer your questions. [^2]
Features
The primary features—Configuration and Routing—are always utilized by users, even in a minimal app setup, without customizations or extra configurations. Ocelot's capabilities are categorized into three main groups of features: solid, hybrid, and feature-family groups, which are explained below.
- Solid features are unique to Ocelot. They do not contain subfeatures and are not related to other features.
- Hybrid features, on the other hand, have multiple relationships with other features and can be part of other features.
- Feature families are large groups that consist of multiple subfeatures.
| Group | Features | |-------|----------| |Primary|Configuration, Routing| | Solid |Caching, Delegating Handlers, Quality of Service[^3], Rate Limiting| | Hybrid|Administration, Aggregation[^4], Authentication, Configuration, Dependency Injection, Load Balancer| |Family|Configuration, Routing, Logging, Transformations, Service Discovery[^5] |
Feature groups are explained in the table below
| Feature | Relationships and Notes |
|---------|-------------------------|
| Administration | Administration heavily depends on Authentication, and Administration API methods are part of Authentication, Caching, and Configuration |
| Aggregation[^4] | Aggregation relies on Routing |
| Authentication | Authentication followed by Authorization |
| Configuration | Configuration depends on Dependency Injection, including GET/POST operations via the Administration REST API, a specialized Websockets scheme/protocol, advanced Middleware Injection, and Metadata-based extensions |
| Routing | Routing offers specialized Websockets and [Dynamic Routing](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html#dynami
