How it works? (quick start)

How it works? (Quick Start)

After adding API Protector .NET library to your project, you will be able to define specific request amount restriction per time unit for each function of your API.

You will be able to protect each method you want, decorating that methods with a single line, like this (the most simple example):

[ApiProtector(ApiProtectionType.ByIdentity, Limit: 5, TimeWindowSeconds: 10)]

(Allows 5 requests per user every 10 seconds)

Indicating in its parameters:
The protection type: ByIdentity (In other words “by user”), ByIpAddress , ByRole , Default.
The limit: How many requests will be allowed (per time interval, specified next).
TimeWindowSeconds: The time interval in which the requests are evaluated.

In normal conditions (while the requests are allowed), your API functions to each request will return normal HTTP status codes like: 200, 201,  202, 204, and others. When the request limit is excedeed in the defined time interval the returned HTTP status code will be 429 (Too many requests).

You do not need any additional code. Just decorate the method, and the library will do the job of monitoring the requests and limiting when the defined threshold is reached.

The protection in action

With our test tool we can see the lib working. We make 10 concurrent requests to a test method that is protected (allows only 5 requests every 10 seconds) …

The first 5 requests are allowed (HTTP 200 status code), while the last 5 requests are reject with a HTTP 429 status code:

We will need to wait 10 seconds for another 5 requests to be allowed. If we try to make another 10 requests before wait 10 seconds, all the request will be rejected because the limit has already been reached:

An informative header

As you can see, in the answers to the allowed requests to protected methods, an informative (and easily parsable) X-API-Protector header is added.

This header inform to the client (in this order):
1) how many allowed requests remains
2) how many requests is the maximum allowed (ie: 5 requests)
3) in which time interval is defined this maximum (expressed in seconds) (ie: 10 seconds)
4) when the time window ends (expressed in Ticks)
5) the penalty (expressed in seconds) (this feature has not yet been presented, we will see it later)

In your application startup, you can customize the header name using the ApiProtectorConfig.HeaderName property, or if you want to disable this feature, you can set this property to null.

Protection types

API Protector .NET has 4 different protection types:

ByIdentity means that “each user will be limited to make N requests in a given time interval to the decorated function”.

ByIpAddress  means that “each different IP address will be limited to make N requests in a given time interval to the decorated function”

ByRole means that “among all the members of a given role, they may make a maximum of N requests in a given time interval to the decorated function” (ie: among all the users with role “seller” can make a maximum of  20 requests per minute). This protection type is useful if it is combined with the others.

Default means that “regardless of which IP, user or role the request comes from,  can be made N requests in a given time interval to the decorated function”.

Combining protections

All the protection types can be combined as much as the imagination allows decorating multiple times the same function.

An example may be:

Let’s analyze this example rule by rule.

First, we limit the function globally to a total of 100 request every 5 seconds regardless of which IP, user or role the request comes from.

Next, we limit the number of requests to 50 every 5 seconds among all users with role “User”. (In example, if a user is in the role “Administrator” this rule will no limit him/her).

After that, we limit the number of requests to 25 every 10 seconds from the same IP.

Next, we limit by identity (by user), to 5 requests every 10 seconds per user. And if this threshold is reached a penalty of 30 seconds is applied to the user. (During 30 seconds the user will be rejected when call this function)

Finally, we limit by identity (by user) again, to a maximum of 1 request per second. And if this threshold is reached by te user, a penalty of 5 seconds is applied. (During 5 seconds the user will be rejected when call this function)

Remember that this is only an example. It is not a best practices guide. You need to design the policy that best fit to your API functions depending on the normal frequency of use and the cost of processing which that functions implies for the server.

Applying penalties

As seen in the previous examples, you can use the parameter PenaltySeconds to define an additional amount of second as a penalty for having reached the limit of requests defined in the rule.

During the defined penalty time, requests to the protected function, which come from the penalized entity, will be rejected.

Exclusions

It is possible to exclude certain trusted users and/or IPs from the defined limits, using the properties ApiProtectorConfig.ExclusionsByIpAddress  and ApiProtectorConfig.ExclusionsByIdentity  in your application startup.

For example:
ApiProtectorConfig.ExclusionsByIpAddress.Add("127.0.0.1");
ApiProtectorConfig.ExclusionsByIdentity.Add("myprettyuser");

Limit reached event handler (attack detection)

It is possible to set an event handler to take action when a defined limit is reached (an attack is detected). In this way, for example, you can log/audit each time that a function of your API is requested beyond the limits,  send notifications to an admin, or set custom logic to auto-modify the protection rules in real time, or any other action that you consider useful.

You can set the event handler in you application startup, using:

internal static void YourStartupMethod() {
   ApiProtectorNotifier.LimitReached += ApiProtectorNotifier_LimitReached;
}

private static void ApiProtectorNotifier_LimitReached(object sender, ApiProtectorEventArgs e) {
   //take your actions here
}

For example: