AWS::ApiGateway::UsagePlan - AWS CloudFormation
SyntaxPropertiesReturn valuesExamplesSee also

AWS::ApiGateway::UsagePlan

The AWS::ApiGateway::UsagePlan resource creates a usage plan for deployed APIs. A usage plan sets a target for the throttling and quota limits on individual client API keys. For more information, see Creating and Using API Usage Plans in Amazon API Gateway in the API Gateway Developer Guide.

In some cases clients can exceed the targets that you set. Don’t rely on usage plans to control costs. Consider using AWS Budgets to monitor costs and AWS WAF to manage API requests.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "Type" : "AWS::ApiGateway::UsagePlan",
  "Properties" : {
      "ApiStages" : [ ApiStage, ... ],
      "Description" : String,
      "Quota" : QuotaSettings,
      "Tags" : [ Tag, ... ],
      "Throttle" : ThrottleSettings,
      "UsagePlanName" : String
    }
}

YAML

Type: AWS::ApiGateway::UsagePlan
Properties:
  ApiStages: 
    - ApiStage
  Description: String
  Quota: 
    QuotaSettings
  Tags: 
    - Tag
  Throttle: 
    ThrottleSettings
  UsagePlanName: String

Properties

ApiStages

The associated API stages of a usage plan.

Required: No

Type: Array of ApiStage

Update requires: No interruption

Description

The description of a usage plan.

Required: No

Type: String

Update requires: No interruption

Quota

The target maximum number of permitted requests per a given unit time interval.

Required: No

Type: QuotaSettings

Update requires: No interruption

Tags

The collection of tags. Each tag element is associated with a given resource.

Required: No

Type: Array of Tag

Update requires: No interruption

Throttle

A map containing method level throttling information for API stage in a usage plan.

Required: No

Type: ThrottleSettings

Update requires: No interruption

UsagePlanName

The name of a usage plan.

Required: No

Type: String

Update requires: No interruption

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the usage plan ID, such as abc123.

For more information about using the Ref function, see Ref.

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

Id

The ID for the usage plan. For example: abc123.

Examples

Create usage plan

The following examples create a usage plan for the Prod API stage, with a quota of 5000 requests per month and a rate limit of 100 requests per second.

JSON

{
    "usagePlan": {
        "Type": "AWS::ApiGateway::UsagePlan",
        "Properties": {
            "ApiStages": [
                {
                    "ApiId": {
                        "Ref": "MyRestApi"
                    },
                    "Stage": {
                        "Ref": "Prod"
                    }
                }
            ],
            "Description": "Customer ABC's usage plan",
            "Quota": {
                "Limit": 5000,
                "Period": "MONTH"
            },
            "Throttle": {
                "BurstLimit": 200,
                "RateLimit": 100
            },
            "UsagePlanName": "Plan_ABC"
        }
    }
}

YAML

usagePlan:
  Type: 'AWS::ApiGateway::UsagePlan'
  Properties:
    ApiStages:
      - ApiId: !Ref MyRestApi
        Stage: !Ref Prod
    Description: Customer ABC's usage plan
    Quota:
      Limit: 5000
      Period: MONTH
    Throttle:
      BurstLimit: 200
      RateLimit: 100
    UsagePlanName: Plan_ABC

See also