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 API stages to associate with this usage plan.
Required: No
Type: List of ApiStage
Update requires: No interruption
Description
-
A description of the usage plan.
Required: No
Type: String
Update requires: No interruption
Quota
-
Configures the number of requests that users can make within a given interval.
Required: No
Type: QuotaSettings
Update requires: No interruption
Tags
An array of arbitrary tags (key-value pairs) to associate with the usage plan.
Required: No
Type: List of Tag
Update requires: No interruption
Throttle
-
Configures the overall request rate (average requests per second) and burst capacity.
Required: No
Type: ThrottleSettings
Update requires: No interruption
UsagePlanName
-
A name for the 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.
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
-
usageplan:create in the Amazon API Gateway REST API Reference