Ocelot .NET (How It Works For Developers)

Ocelot API Gateway is a .NET library that implements the API gateway pattern commonly used in API gateways, to handle requests across multiple microservices. It acts as a lightweight API gateway, routing requests from clients to downstream service. This article provides an in-depth look at how the Ocelot API gateway sits between clients and downstream services, covering its installation, configuration, key features, and practical examples to demonstrate its capabilities. We'll also explore IronPDF and Ocelot API combined.

What is Ocelot .NET?

Ocelot is an open-source API gateway solution for .NET applications, designed to facilitate the routing of requests across multiple microservices. It acts as a reverse proxy, managing HTTP requests from clients and routing them to the appropriate services in an ASP.NET Core environment. Developed on ASP.NET Core, Ocelot integrates seamlessly with the .NET ecosystem, offering a robust set of features that are crucial for modern applications.

Key Features of Ocelot

Routing

At the core of Ocelot's functionality is its routing capability. It matches incoming requests to the appropriate service routes based on the configuration specified by developers, and it can be integrated with service discovery mechanisms. This includes support for wildcard routing, which is particularly useful when dealing with varying API versions or numerous service endpoints.

Middleware / Delegating Handlers

Ocelot allows developers to inject custom middleware or handlers that can process requests and responses before they reach the client or the service. This is useful for adding headers, logging requests, or even modifying the response structure as needed.

Load Balancing

Ocelot supports a variety of load-balancing strategies out of the box, such as Round Robin, Least Connection, and a custom provider if none of the predefined strategies fit the requirement. This feature ensures that the load is distributed evenly among the available services, enhancing the overall resilience and efficiency of the application.

Authentication and Authorization

Securing API endpoints is critical, and Ocelot provides support for integrating with existing authentication providers, such as Identity Server. It supports popular authentication schemes, including JWT and OAuth2, and allows for fine-grained control over user access to services.

Rate Limiting and QoS

Rate limiting is essential to prevent abuse and ensure fair use of the services by limiting the number of requests a user can make in a given period. Quality of Service (QoS) options like setting timeouts and retries ensure that services remain available and responsive under various network conditions and loads.

Setting Up Ocelot in a .NET Project

To integrate Ocelot into your project, you need to install the Ocelot package via NuGet and configure it in the Program class:

Install-Package IronPdf

Configure the services, including the request builder middleware, in your Startup.cs or Program class to set up the service container:

public void ConfigureServices(IServiceCollection services)
{
    services.AddOcelot();
}
public async void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // Optionally handle ASP.NET Core environment settings
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    // Start Ocelot
    await app.UseOcelot();
}

public void ConfigureServices(IServiceCollection services)
{
    services.AddOcelot();
}
public async void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // Optionally handle ASP.NET Core environment settings
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    // Start Ocelot
    await app.UseOcelot();
}

Public Sub ConfigureServices(ByVal services As IServiceCollection)
	services.AddOcelot()
End Sub
Public Async Sub Configure(ByVal app As IApplicationBuilder, ByVal env As IWebHostEnvironment)
	' Optionally handle ASP.NET Core environment settings
	If env.IsDevelopment() Then
		app.UseDeveloperExceptionPage()
	End If
	' Start Ocelot
	Await app.UseOcelot()
End Sub

Configuring Routes in Ocelot

Ocelot uses a configuration file, typically ocelot.json, to define the routing rules. Here is a more complex example that demonstrates multiple route configurations:

{
    "ReRoutes": [
        {
            "DownstreamPathTemplate": "/api/users/{id}",
            "DownstreamScheme": "https",
            "DownstreamHostAndPorts": [
                {
                    "Host": "userapi.com",
                    "Port": 443
                }
            ],
            "UpstreamPathTemplate": "/users/{id}",
            "UpstreamHttpMethod": ["Get"]
        },
        {
            "DownstreamPathTemplate": "/api/products/{id}",
            "DownstreamScheme": "https",
            "DownstreamHostAndPorts": [
                {
                    "Host": "productapi.com",
                    "Port": 443
                }
            ],
            "UpstreamPathTemplate": "/products/{id}",
            "UpstreamHttpMethod": ["Get"]
        }
    ],
    "GlobalConfiguration": {
        "BaseUrl": "http://yourgateway.com"
    }
}

This configuration specifies how requests to the API gateway are routed to different downstream services based on the path and HTTP method, using the JSON file for setup.

Using IronPDF with Ocelot .NET

Combining Ocelot with IronPDF in a .NET application provides a powerful solution where you can route PDF generation requests to a specific service or handle them internally. Here, I'll guide you through setting up a basic .NET Core application that uses Ocelot as an API Gateway and IronPDF to generate PDFs from HTML.

Step 1: Set Up the .NET Core Web Application

First, create a new .NET Core Web API project. You can do this using the .NET CLI or Visual Studio.

Using the .NET:

dotnet new webapi -n OcelotWithIronPDF
cd OcelotWithIronPDF

Step 2: Add Necessary Packages

You need to install Ocelot and IronPDF. You can add these packages via NuGet.

dotnet add package Ocelot
dotnet add package IronPdf

Step 3: Configure Ocelot

Add an ocelot.json file to the root of your project with the following content to configure Ocelot’s routing. This setup assumes you want Ocelot to route PDF generation requests to a specific path that will be handled by IronPDF within the same application.

{
    "ReRoutes": [
        {
            "DownstreamPathTemplate": "/api/pdf",
            "DownstreamScheme": "https",
            "DownstreamHostAndPorts": [
                {
                    "Host": "localhost",
                    "Port": 5001
                }
            ],
            "UpstreamPathTemplate": "/generatepdf",
            "UpstreamHttpMethod": ["Post"]
        }
    ],
    "GlobalConfiguration": {
        "BaseUrl": "http://localhost:5000"
    }
}

Step 4: Configure Startup.cs

Update Startup.cs to include Ocelot’s middleware. Ensure you also configure your application to use static files, as IronPDF may need to load assets from the local file system.

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
        services.AddOcelot();
    }
    public async void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        app.UseRouting();
        app.UseAuthorization();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
        await app.UseOcelot();
    }
}

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
        services.AddOcelot();
    }
    public async void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        app.UseRouting();
        app.UseAuthorization();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
        await app.UseOcelot();
    }
}

Public Class Startup
	Public Sub ConfigureServices(ByVal services As IServiceCollection)
		services.AddControllers()
		services.AddOcelot()
	End Sub
	Public Async Sub Configure(ByVal app As IApplicationBuilder, ByVal env As IWebHostEnvironment)
		If env.IsDevelopment() Then
			app.UseDeveloperExceptionPage()
		End If
		app.UseRouting()
		app.UseAuthorization()
		app.UseEndpoints(Sub(endpoints)
			endpoints.MapControllers()
		End Sub)
		Await app.UseOcelot()
	End Sub
End Class

Step 5: Implement PDF Generation with IronPDF

Create a new controller PdfController.cs in your Controllers folder. This controller will handle the PDF generation requests.

using Microsoft.AspNetCore.Mvc;
using IronPdf;
namespace OcelotWithIronPDF.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class PdfController : ControllerBase
    {
        [HttpPost]
        public IActionResult CreatePdfFromHtml([FromBody] string htmlContent)
        {
            var renderer = new ChromePdfRenderer();
            var pdf = renderer.RenderHtmlAsPdf(htmlContent);
            var output = pdf.BinaryData;
            return File(output, "application/pdf", "generated.pdf");
        }
    }
}

using Microsoft.AspNetCore.Mvc;
using IronPdf;
namespace OcelotWithIronPDF.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class PdfController : ControllerBase
    {
        [HttpPost]
        public IActionResult CreatePdfFromHtml([FromBody] string htmlContent)
        {
            var renderer = new ChromePdfRenderer();
            var pdf = renderer.RenderHtmlAsPdf(htmlContent);
            var output = pdf.BinaryData;
            return File(output, "application/pdf", "generated.pdf");
        }
    }
}

Imports Microsoft.AspNetCore.Mvc
Imports IronPdf
Namespace OcelotWithIronPDF.Controllers
	<ApiController>
	<Route("api/[controller]")>
	Public Class PdfController
		Inherits ControllerBase

		<HttpPost>
		Public Function CreatePdfFromHtml(<FromBody> ByVal htmlContent As String) As IActionResult
			Dim renderer = New ChromePdfRenderer()
			Dim pdf = renderer.RenderHtmlAsPdf(htmlContent)
			Dim output = pdf.BinaryData
			Return File(output, "application/pdf", "generated.pdf")
		End Function
	End Class
End Namespace

Step 6: Run the Application

Make sure your application is correctly configured to listen on the ports specified in ocelot.json. You can set this in Properties/launchSettings.json.

{
  "profiles": {
    "OcelotWithIronPDF": {
      "commandName": "Project",
      "launchBrowser": false,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Now, run your application, and you should be able to post HTML content to http://localhost:5000/generatepdf and receive a PDF in response.

This example showcases a basic implementation of Ocelot with IronPDF within the same application. For production scenarios, consider securing your endpoints, handling error scenarios, and optimizing the PDF generation process based on your specific requirements.

Conclusion

In conclusion, Ocelot is an excellent choice for managing and routing requests in a microservices architecture. Its robust features like routing, load balancing, middleware support, and authentication make it a powerful tool for any .NET developer. By following the detailed steps provided, you can effectively integrate Ocelot into your .NET projects to streamline your API Gateway needs.

Additionally, if you require PDF generation capabilities, integrating IronPDF with Ocelot is straightforward and enhances your application's functionality. IronPDF offers a free trial, and licenses start from $749, providing a cost-effective solution for your PDF needs.

By leveraging Ocelot and IronPDF together, you can build a comprehensive and efficient microservices infrastructure that meets both routing and document generation requirements.