11436 SSO

Tutorial: Protect your Apigee-127 API with Spike Arrest

Jan 06, 2015

Apigee-127 includes several policies to monitor and modify the behavior of your API. The spike arrest policy enables you to identify and prevent sudden bursts of traffic that could indicate a malicious DDoS attack or even a buggy client app gone off the rails.

What's the difference between spike arrest and quota?

It’s important to choose the right tool for the job at hand. Quota policies configure the number of request messages that a client app is allowed to submit to an API over the course of an hour, day, week, or month. The quota policy enforces consumption limits on client apps by maintaining a distributed counter that tallies incoming requests.

Use a quota policy to enforce business contracts or SLAs with developers and partners, rather than for operational traffic management. For example, a quota might be used to limit traffic for a free service, while allowing full access for paying customers.

Use spike arrest to protect against sudden spikes in API traffic. Typically, spike arrest is used to head off possible DDoS or other malicious attacks.

Configuring spike arrest

Adding spike arrest to your API is simple. It follows the same pattern used for other policies, like quota and cache.

First, configure the policy in the "x-a127-services" block of your Swagger YAML file. For example:

         provider: <volos-provider>
           timeUnit: <time-unit>
           bufferSize: <buffer-size>
           allow: <number-of-requests-to-allow>

Here's an example of a complete spike arrest definition:

       provider: "volos-spikearrest-memory"
         timeUnit: "minute"
         bufferSize: 3
         allow: 30


There are several options we can configure for our spike arrest policy:

  • spike-arrest-name -- The name of our spike arrest definition. This can be anything you want, and allows you to define multiple spike arrest policies within a single API, then apply them to the desired paths by name. More on applying spike arrest policies later.

  • volos-provider -- Where the spike arrest settings and counts will be stored. Apigee-127 supports these providers:

    • volos-spikearrest-memory

    • volos-spikearrest-apigee (Note: There is no inherent advantage to choosing one spike arrest provider over another. It’s a design decision, and should usually be based on what provider you are using for other services, such as OAuth and caching. If you’re deploying your Apigee-127 API to Apigee, for example, then it makes sense to also use Apigee as your spike arrest provider.)

  • timeUnit -- The time span over which the spike arrest policy enforces the allowed number of requests; you can specify minute or second

  • allow -- The number of requests that can be processed in the span of a time unit

  • bufferSize -- Without a buffer, Apigee-127 returns a spike arrest error as soon as the limit is exceeded; the buffer is used to store a queue of requests that will be processed one at a time when the next available execution window occurs.

Applying spike arrest

Applying a spike arrest policy is even easier than configuring it. Just add the following to the “x-a127-apply” block attached to any “path” in your Swagger YAML file, where <spike-arrest-name> is the name you specified in "x-a127-services":

   <spike-arrest-name>: {}

How does spike arrest work?

Let's say you specify a "timeUnit" of one minute and the "allow" value is 30. You might think that this would allow thirty API calls in one second, as long as they came within a minute. But that's not how the policy enforces the setting.

What actually happens? To prevent spike-like behavior, spike arrest smooths the allowed traffic by dividing your settings into smaller intervals. So, for example, per-minute rates get smoothed into allowed intervals of seconds, like this:

  • sixty seconds (1 minute) / 30 = two-second intervals, or about one request allowed every two seconds; a second request inside of two seconds will fail, as will a 31st request within a minute

For a deeper dive

For more information about how spike arrest is enforced for different time units, as well as advanced settings and information on using helper functions to customize spike arrest behavior, see Spike arrest deep dive on the Apigee-127 documentation wiki.

Also, check out the spike arrest sample in the Apigee-127/a127-samples repo on GitHub.

That’s it! For more on applying API management features in Apigee-127, check out our blog posts on using caching, OAuth 2.0, quota, and programmatic access to Apigee-127 services, and visit our Apigee-127 YouTube playlist.


Scaling Microservices