Part Four - Building API Gateway Using Ocelot In ASP.NET Core - Rate Limiting


In the previous articles of this series, we discussed how to build the API Gateway in ASP.NET Core. 

And in this article, we will discuss Rate Limiting module of Ocelot.

If you want to look at the previous articles of this series, please visit the links given below.

What is Rate Limiting? 

Wikipedia tells us that rate limiting is used to control the rate of traffic sent or received by a network interface controller and is used to prevent DoS attacks.

Most APIs are subject to a limit on how many calls can be made per second (or minute, or another short time period), in order to protect servers from being overloaded and maintain the high quality of service to many clients.

Now, let's take a look at how to use Ocelot to accomplish rate limiting.

I will use version 3.1.5 of Ocelot to build a sample.


We need to create two projects and ensure that they can run well.

As usual, create two projects at first: 

Project NameProject TypeDescription
APIGatewayASP.NET Core EmptyThis is the entry of this demo.
APIServicesASP.NET Core Web APIThis is an API Service that provides some services. 

Add a basic configuration.json file to APIGateway project.

  1. {  
  2.     "ReRoutes": [  
  3.         {  
  4.             "DownstreamPathTemplate""/api/values",  
  5.             "DownstreamScheme""http",  
  6.             "DownstreamHostAndPorts": [  
  7.                 {  
  8.                     "Host""localhost",  
  9.                     "Port": 9001  
  10.                 }  
  11.             ],  
  12.             "UpstreamPathTemplate""/customers",  
  13.             "UpstreamHttpMethod": [ "Get" ]  
  14.         },  
  15.         {  
  16.             "DownstreamPathTemplate""/api/values/{id}",  
  17.             "DownstreamScheme""http",  
  18.             "DownstreamHostAndPorts": [  
  19.                 {  
  20.                     "Host""localhost",  
  21.                     "Port": 9001  
  22.                 }  
  23.             ],  
  24.             "UpstreamPathTemplate""/customers/{id}",  
  25.             "UpstreamHttpMethod": [ "Get" ]  
  26.         }  
  27.     ],  
  28.     "GlobalConfiguration": {  
  29.         "RequestIdKey""OcRequestId",  
  30.         "AdministrationPath""/administration"  
  31.     }  
  32. }  


Please pay attention to node DownstreamHostAndPorts. In previous versions of Ocelot, this node uses DownstreamHost and DownstreamPort to replace.

Run those two projects and you may get the following result.

ASP.NET Core   

It means that our preparation is done. Now, we will add configuration of rate limiting to http://localhost:9000/customers.

Add Rate Limiting In configuration.json

We only need to add a node named RateLimitOptions. The following code shows the basic configuration.

  1. {  
  2.     "DownstreamPathTemplate""/api/values",  
  3.     "DownstreamScheme""http",  
  4.     "DownstreamHostAndPorts": [  
  5.         {  
  6.             "Host""localhost",  
  7.             "Port": 9001  
  8.         }  
  9.     ],  
  10.     "UpstreamPathTemplate""/customers",  
  11.     "UpstreamHttpMethod": [ "Get" ],  
  12.     "RateLimitOptions": {  
  13.         "ClientWhitelist": [],  
  14.         "EnableRateLimiting"true,  
  15.         "Period""1s",  
  16.         "PeriodTimespan": 1,  
  17.         "Limit": 1  
  18.     }  
  19. }  
  20. //others.....  

Let's take a look at the RateLimitOptions node.

  1. ClientWhitelist
    This is an array that contains the whitelist of the client. It means that the client in this array will not be affected by the rate limiting.
  1. EnableRateLimiting
    This value specifies enable endpoint rate limiting.
  1. Period
    This value specifies the period, such as 1s, 5m, 1h,1d and so on.
  1. PeriodTimespan
    This value specifies that we can retry after a certain number of seconds.
  1. Limit
    This value specifies the maximum number of requests that a client can make in a defined period.

In the above configuration, we can only visit once per second.

Let's take a look at the result after adding rate limiting:

As you can see, it tells us that API calls quota exceeded! maximum admitted 1 per 1s. when we visit quickly in a second.  You also can see the following screenshot.


The response status code is 429(Too Many Requests). And in response headers, it contains Retry-After which means that we should have a retry after 1 second.

Some More Configuration

We have finished the rate limiting in the previous step. 

However, you may ask three questions here:

  1. Can we replace the default prompts?
  2. Can we remove the response header of rate limiting?
  3. Can we change the response status code?

The answer to all of those questions is yes.

If we want to change those settings, we need to add some global configuration.

  1. "GlobalConfiguration": {  
  2.     "RequestIdKey""OcRequestId",  
  3.     "AdministrationPath""/administration",  
  4.     "RateLimitOptions": {  
  5.       "DisableRateLimitHeaders"false,  
  6.       "QuotaExceededMessage""Customize Tips!",  
  7.       "HttpStatusCode": 999  
  8.     }  
  9.   }  

Let's take a look at the RateLimitOptions node in GlobalConfiguration!

  1. DisableRateLimitHeaders
    This value specifies whether X-Rate-Limit and Rety-After headers are disabled.
  1. QuotaExceededMessage
    This value specifies the exceeded message.
  1. HttpStatusCode
    This value specifies the returned HTTP Status code when rate limiting occurs.

After adding those configurations, we can get the results as follows.


Here is the source code you can find on my Github page.


This article introduced how to use Rate Limiting module in Ocelot.

Hope this can help you!