API Gateway for Microservices in C#: Complete Guide

Why Does Your C# Project Need an API Gateway?

Imagine you are building a modern web application in C#. You have a user service, an order service, a payment service — and each one lives on its own port, or even on different servers. The client application (frontend or mobile app) must know about all these addresses, data formats, and authentication protocols. A nightmare, right?

This is where the API Gateway for C# services comes into play — a single entry point that handles all the "dirty work": routing, response aggregation, token validation, caching, and load balancing. In this article, we will break down how to implement a .NET API gateway in practice, using modern tools like Ocelot C# and YARP .NET.

What is an API Gateway and Why Do Microservices Need It?

An API Gateway is an intermediary layer between clients and your backend services. It acts as a "dispatcher": it receives incoming HTTP requests, analyzes them, and forwards them to the appropriate C# microservices. Additionally, the gateway can perform extra tasks:

\n
• Request routing — directing requests to different services based on URL, headers, or parameters.
\n
• Data aggregation — collecting responses from multiple services and returning a single JSON to the client.
\n
• API Gateway authentication — verifying JWT tokens or API keys before the request reaches the service.
\n
• Load balancing — distributing requests among instances of the same service.
\n
• Caching — temporarily storing responses for frequently requested data.
\n
• Rate Limiting — limiting the number of requests from a single client.
\n

Without a .NET API gateway, each client must know the entire system architecture. With it, the client communicates with only one endpoint, and everything else happens "under the hood."

Two Main Tools for API Gateway in C#

In the .NET ecosystem, there are two powerful solutions worth your attention:

Ocelot C#

Arguably the most popular API Gateway for C# services. Ocelot is an open-source library that adds gateway functionality to any ASP.NET Core application. It supports:

\n
• JSON-based configuration routing
\n
• Response aggregation
\n
• Authentication and authorization
\n
• Rate limiting
\n
• Load balancing (RoundRobin, LeastConnection)
\n
• WebSockets
\n

YARP .NET (Yet Another Reverse Proxy)

A project from Microsoft positioned as a high-performance reverse proxy. YARP is more flexible and performant but requires more manual configuration. It is an excellent choice if you need full control over every request.

In this article, we will focus on Ocelot — it is easier to get started with and covers 90% of typical tasks.

Creating an API Gateway in C# with Ocelot: Step-by-Step Guide

Let's write some real code. We will create a .NET API gateway that routes requests to two microservices: UserService (port 5001) and OrderService (port 5002).

Step 1: Create the Project

Open your terminal and run:

dotnet new webapi -n ApiGatewayDemo\ncd ApiGatewayDemo

Install the Ocelot package:

dotnet add package Ocelot

Step 2: Configure Route Settings

Create a file named ocelot.json in the project root. In it, we will describe the routing rules:

{\n  "Routes": [\n    {\n      "DownstreamPathTemplate": "/api/users/{everything}",\n      "DownstreamScheme": "http",\n      "DownstreamHostAndPorts": [\n