Skip to content

API Gateway Default Throttling

Level: Error

Initial version: 0.1.3

cfn-lint: ES2003

tflint (REST): aws_apigateway_stage_throttling_rule

tflint (HTTP): aws_apigatewayv2_stage_throttling_rule

Amazon API Gateway supports defining default limits for an API to prevent it from being overwhelmed by too many requests. This uses a token bucket algorithm, where a token counts for a single request.

AWS SAM templates

For SAM REST APIs, this rule requires a wildcard MethodSettings entry (HttpMethod: "*", ResourcePath: "/*") with both ThrottlingBurstLimit and ThrottlingRateLimit; throttling declared only for a specific route does not count as a default. SAM HTTP APIs use DefaultRouteSettings with both limits. For AWS::Serverless::Api and AWS::Serverless::HttpApi resources, this rule checks the effective stage settings directly, including values inherited from Globals.Api or Globals.HttpApi. Function Api events without RestApiId and HttpApi events without ApiId create implicit APIs, which are also checked using the applicable global settings; each implicit API finding is reported once per owning function, so functions sharing an implicit API can each receive a finding.

Implementations for REST APIs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { RestApi } from '@aws-cdk/aws-apigateway';

export class MyStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const myApi = new RestApi(
      scope, 'MyApi',
      {
        deployOptions: {
          // Throttling for default methods
          methodOptions: {
            '*/*': {
              throttlingBurstLimit: 1000,
              throttlingRateLimit: 10,
            }
          }
        },
      }
    );
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "Resources": {
    "MyApi": {
      "Type": "AWS::Serverless::Api",
      "Properties": {
        "DefinitionUri": "openapi.yaml",
        "StageName": "prod",
        // Throttling for default methods by setting HttpMethod  to '*' and
        // ResourcePath to '/*'
        "MethodSettings": [{
          "HttpMethod": "*",
          "ResourcePath": "/*",
          "ThrottlingRateLimit": 10,
          "ThrottlingBurstLimit": 1000
        }]
      }
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
Resources:
  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      DefinitionUri: openapi.yaml
      StageName: prod

      # Throttling for default methods by setting HttpMethod  to '*' and
      # ResourcePath to '/*'
      MethodSettings:
        - HttpMethod: "*"
          ResourcePath: "/*"
          ThrottlingRateLimit: 10
          ThrottlingBurstLimit: 1000

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
resources:
  Resources:
    MyApi:
      Type: AWS::Serverless::Api
      Properties:
        DefinitionUri: openapi.yaml
        StageName: prod

        # Throttling for default methods by setting HttpMethod  to '*' and
        # ResourcePath to '/*'
        MethodSettings:
          - HttpMethod: "*"
            ResourcePath: "/*"
            ThrottlingRateLimit: 10
            ThrottlingBurstLimit: 1000

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
resource "aws_api_gateway_stage" "this" {
  body = file("openapi.yaml") 
}

resource "aws_api_gateway_deployment" "this" {
  rest_api_id = aws_api_gateway_rest_api.this.id

  triggers = {
    redeployment = sha1(jsonencode(aws_api_gateway_rest_api.this.body))
  }

  lifecycle {
    create_before_destroy = true
  }
}

resource "aws_api_gateway_stage" "this" {
  deployment_id = aws_api_gateway_deployment.this.id
  rest_api_id   = aws_api_gateway_rest_api.this.id
  stage_name    = "prod"
}

# Throttling for default methods by setting method_path to '*/*'
resource "aws_api_gateway_method_settings" "this" {
  rest_api_id = aws_api_gateway_rest_api.this.id
  stage_name  = aws_api_gateway_stage.this.stage_name
  method_path = "*/*"

  settings {
    throttling_burst_limit = 1000
    throttling_rate_limit  = 10
  }
}

Implementations for HTTP APIs

Remark: this is currently not supported in AWS CDK as an L2 construct at the moment.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import { CfnStage, HttpApi } from '@aws-cdk/aws-apigatewayv2';

export class MyStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const myApi = new HttpApi(
      scope, 'MyApi'
    );

    // Throttling for default methods by setting method_path to '*/* using escape hatch.

    // See https://docs.aws.amazon.com/cdk/latest/guide/cfn_layer.html#cfn_layer_resource
    // for more information.
    const defaultStage = myApi.defaultStage.node.defaultChild as CfnStage;
    defaultStage.defaultRouteSettings = {
      throttlingBurstLimit = 1000,
      throttlingRateLimit = 10,
    };
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "Resources": {
    "MyApi": {
      "Type": "AWS::Serverless::HttpApi",
      "Properties": {
        "DefinitionUri": "openapi.yaml",
        "StageName": "prod",
        "DefaultRouteSettings": {
          "ThrottlingBurstLimit": 1000,
          "ThrottlingRateLimit": 10
        }
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
Resources:
  MyApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      DefinitionUri: "openapi.yaml"
      StageName: prod
      DefaultRouteSettings:
        ThrottlingBurstLimit: 1000
        ThrottlingRateLimit: 10

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
resources:
  Resources:
    MyApi:
      Type: AWS::Serverless::HttpApi
      Properties:
        DefinitionUri: "openapi.yaml"
        StageName: prod
        DefaultRouteSettings:
          ThrottlingBurstLimit: 1000
          ThrottlingRateLimit: 10

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
resource "aws_apigatewayv2_api" "this" {
  name          = "my-api"
  protocol_type = "HTTP"
  body          = file("openapi.yaml") 
}

resource "aws_apigatewayv2_stage" "this" {
  api_id = aws_apigatewayv2_api.this.id
  name   = "prod"

  # Default throttling settings
  default_route_settings {
    throttling_burst_limit = 1000
    throttling_rate_limit  = 10
  }
}

See also