Introduction

In modern applications, we often split our system into multiple smaller services called Microservices. Each service is responsible for a specific business function.

For example:

• User Service → Handles users
• Product Service → Handles products
• Order Service → Handles orders

When we have multiple services, clients need a simple way to access them. Instead of calling each service directly, we use an API Gateway.

In this tutorial, we'll build:

• User Microservice
• Product Microservice
• Ocelot API Gateway

By the end of this article, you'll understand how API Gateway routing works and how Ocelot can help manage communication between microservices.

What We Are Building

Our architecture will look like this:

Browser / Postman
        |
        v
   API Gateway
      (Ocelot)
      /     \
     /       \
    v         v
User API   Product API

Instead of calling User API or Product API directly, all requests will go through the API Gateway.

Step 1: Create the Solution

Open Visual Studio and create:

Project 1: UserService

dotnet new webapi -n UserService

Project 2: ProductService

dotnet new webapi -n ProductService

Project 3: ApiGateway

dotnet new webapi -n ApiGateway

Your solution structure should look like:

MicroserviceDemo
|
├── ApiGateway
├── UserService
└── ProductService

Step 2: Create User Service

Open UserService and create a controller.

[ApiController]
[Route("user")]
public class UserController : ControllerBase
{
    [HttpGet]
    public IActionResult GetUser()
    {
        return Ok(new
        {
            Id = 1,
            Name = "John Doe"
        });
    }
}

Run the application.

Test:

https://localhost:7044/user

Response:

{
  "id": 1,
  "name": "John Doe"
}

Great! Our User Service is working.

Step 3: Create Product Service

Now create a ProductController.

[ApiController]
[Route("product")]
public class ProductController : ControllerBase
{
    [HttpGet]
    public IActionResult GetProduct()
    {
        return Ok(new
        {
            Id = 100,
            Name = "Laptop"
        });
    }
}

Run Product Service.

Test:

https://localhost:7220/product

Response:

{
  "id": 100,
  "name": "Laptop"
}

Now both microservices are working independently.

Step 4: Why Do We Need an API Gateway?

At this point, the client needs to know:

https://localhost:7044/user

https://localhost:7220/product

Imagine having 20 microservices.

The frontend would need to manage 20 different URLs.

This becomes difficult to maintain.

An API Gateway solves this problem by providing a single entry point.

Example:

https://localhost:5000/gateway/user

https://localhost:5000/gateway/product

The gateway automatically forwards requests to the correct service.

Step 5: Install Ocelot

Open Package Manager Console inside ApiGateway.

Install Ocelot:

Install-Package Ocelot

or

dotnet add package Ocelot

Ocelot is a popular API Gateway library built specifically for ASP.NET Core.

Step 6: Create Ocelot Configuration

Create a new file:

ocelot.json

Add:

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/user",
      "DownstreamScheme": "https",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 7044
        }
      ],
      "UpstreamPathTemplate": "/gateway/user",
      "UpstreamHttpMethod": [ "GET" ]
    },
    {
      "DownstreamPathTemplate": "/product",
      "DownstreamScheme": "https",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 7220
        }
      ],
      "UpstreamPathTemplate": "/gateway/product",
      "UpstreamHttpMethod": [ "GET" ]
    }
  ]
}

Let's understand what this means.

When someone calls:

/gateway/user

Ocelot forwards the request to:

/user

inside User Service.

Similarly:

/gateway/product

is forwarded to Product Service.

Step 7: Configure Ocelot in Program.cs

Open ApiGateway Program.cs.

Replace the code with:

using Ocelot.DependencyInjection;
using Ocelot.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile(
    "ocelot.json",
    optional: false,
    reloadOnChange: true);

builder.Services.AddOcelot();

var app = builder.Build();

await app.UseOcelot();

app.Run();

This tells the application:

• Load Ocelot configuration
• Enable API Gateway middleware
• Route requests using ocelot.json

Step 8: Test the Gateway

Start:

• UserService
• ProductService
• ApiGateway

Now call:

https://localhost:5000/gateway/user

Expected Response:

{
  "id": 1,
  "name": "John Doe"
}

Call:

https://localhost:5000/gateway/product

Expected Response:

{
  "id": 100,
  "name": "Laptop"
}

Notice something important.

The client never talks directly to User Service or Product Service.

Everything goes through the API Gateway.

Step 9: Add Rate Limiting

Suppose we want to allow only 4 requests per minute.

Update User Route:

"RateLimitOptions": {
  "EnableRateLimiting": true,
  "Period": "60s",
  "Limit": 4
}

Now:

• Request 1 → Success
• Request 2 → Success
• Request 3 → Success
• Request 4 → Success
• Request 5 → Blocked

Response:

429 Too Many Requests

This helps protect APIs from abuse.

Step 10: Add Load Balancing

Suppose User Service is getting heavy traffic.

We create another instance running on:

https://localhost:7045/user

Update Ocelot:

"DownstreamHostAndPorts": [
  {
    "Host": "localhost",
    "Port": 7044
  },
  {
    "Host": "localhost",
    "Port": 7045
  }
],
"LoadBalancerOptions": {
  "Type": "RoundRobin"
}

How it works:

Request 1 → Server 1

Request 2 → Server 2

Request 3 → Server 1

Request 4 → Server 2

Traffic gets distributed automatically.

Conclusion

In this guide, we built a simple Microservices Architecture using .NET 8 and Ocelot API Gateway. We started by creating separate User and Product services, then configured Ocelot to act as a central entry point for routing requests to the appropriate service.

Along the way, we learned how API Gateways simplify communication between clients and microservices, how route configuration works, and how features like rate limiting and load balancing can improve the reliability and scalability of an application.

While this example is intentionally simple, the same concepts are used in real-world enterprise applications. As systems grow, an API Gateway becomes an important component for managing traffic, securing APIs, and providing a consistent entry point for consumers.

If you're new to Microservices, I recommend experimenting further by adding:

• JWT Authentication
• Health Checks
• Swagger Aggregation
• Docker Containers
• Service Discovery
• Distributed Logging

These additions will help you move from a basic microservices setup to a production-ready architecture.

I hope this article helped you understand how Ocelot works and how it can be used to build scalable .NET applications. If you have any questions or suggestions, feel free to leave a comment or connect with me.