Sitecore Experience Management

Throttle requests

Abstract

Restrict frequency of requests made through the OData service

Note

This topic describes features that are valid for Sitecore 9, Update 2, and later.

You can throttle the number of requests made to Sitecore.Services.Client. You might want to do this:

  • To restrict the request frequency.

  • To use different strategies for servicing requests based on user type (for example, free versus paid).

  • To prevent high-frequency request attacks.

This topic describes:

Sitecore.Services.Client provides an API you can use to limit the number of requests per time interval. By default, Sitecore.Services.Client has two throttle strategies:

  • Sliding window – Specify a time interval and the number of allowed requests in that interval. Sitecore throttles further requests.

  • Composite – You compose multiple strategies into one.

Note

You cannot include a strategy in itself because this would create a circular reference.

For example, you can compose a number of sliding window strategies that have different parameters. The first one rejects requests after a small time span (1-5 seconds), the second rejects requests after a much longer time span (24h).

Note

In a scaled environment, Sitecore does not share strategy states across instances. Strategies have their own state on each instance.

Throttling is disabled by default. You enable throttling by patching the App_Config\Sitecore\Services.Client Sitecore.Services.Client.config file in the following way:

  • Change the value of <setting name="Sitecore.Services.IsThrottleEnabled" value="false" /> to true.

Strategies are in the core database under /sitecore/system/Settings/Services/Throttle Strategies.

You can add strategies directly under Throttle Strategies, or you can create a subfolder (Strategy Folder) and add strategies in the subfolder.

You must specify a value for the Type field in the Common Options section for each strategy item. The value is the full name of the class that implements the strategy, for example, Sitecore.Services.Infrastructure.Throttle.Strategies.SlidingWindowThrottleStrategy, Sitecore.Services.Infrastructure.

A strategy item contains a specific set of parameters that depend on the strategy type. The parameters specify the behavior of the strategy.

For example, for a sliding window strategy:

Throttle_requests-Picture_2-rId10-1106920143.png

For example, for a composite strategy:

Throttle_requests-Picture_10-rId11-252023046.png

You can apply a strategy in three ways:

  • Use an API Key.

  • Use a method of an API controller (attribute-based throttle).

  • Use an API controller.

You can use these methods in any combination. Sitecore combines the outcomes of the strategies.

Sitecore uses the following rules when it applies two or more strategies for a request:

  • If you specify the same strategy in multiple ways, Sitecore only applies it once.

  • If you specify multiple strategies for a method or a controller, Sitecore combines the strategies.

If you use the same strategy multiple times, the strategies share the state. For example, if you specify a sliding window strategy with the Time Span = 1000 ms and Allowed Number of Requests = 5 requests parameters and apply it on two services, the outcome is that only 5 requests in total are possible in any 1000 ms window.

If an error results when Sitecore applies a strategy, the request receives an Internal Server Error (code 500).

Using an API Key

When you apply a strategy using an API key, Sitecore applies the strategy to all Sitecore.Services.Client requests that use this API key. You can apply a strategy using an API Key as well as an OData API Key.

For example:

[ServicesController]
[RequiredApiKey]
public class SampleController : ApiController
    [Route("api/throttle/datawithkey")]
    public IEnumerable<string> GetData()
    {
        return new[]
        {
            "The Key : " + Guid.NewGuid()
        };
    }
}

In the example, the [RequiredApiKey] attribute is defined, and an API key is mandatory to access this controller. Sitecore checks if an API key is valid and ready to use. If the key is valid, Sitecore applies any defined strategy to the request.

You define a strategy in the Throttle Strategy field in the Data section of an API key item.

Using an API controller method

To apply a strategy to an API controller method, define your controller and apply strategies directly to actions. For example:

[ServicesController]
public class SampleController : ApiController
{
    [Throttle("Sliding Window")]
    [Route("api/throttle/data")]
    public IEnumerable<string> GetData()
    {
        return new[]
        {
            "The Key : " + Guid.NewGuid()
        };
    }
    [Throttle("Composite")]
    [Route("api/throttle/compositedata")]
    public IEnumerable<string> GetCompositeData()
    {
        return new[]
        {
            "The Key : " + Guid.NewGuid()
        };
    }
}

Using a controller

To apply a strategy to a controller, define the controller and then apply strategies to the class of controller. For example:

[RequiredApiKey]
[Throttle("07 On Controller")]
public class ThrottledOnControllerController : ApiController
{
        [Route("api/ThrottledOnController/data")]
        public IEnumerable<string> GetData()
        {
            return new[] { "Controller api/ThrottledOnController/data was called: " + DateTime.Now };
        }
}

Sitecore applies the 07 On Controller strategy to any methods of the ThrottledOnControllerController controller.