Create, configure, and
test usage plans with the API Gateway console
Before creating a usage plan, make sure that you've set up the desired API keys. For
more information, see Set up API keys using the API Gateway console.
This section describes how to create and use a usage plan by using the API Gateway
console.
Migrate your API to
default usage plans (if needed)
If you started to use API Gateway after the usage plans feature was
rolled out on August 11, 2016, you will automatically have usage plans enabled for
you in all supported Regions.
If you started to use API Gateway before that date, you might need to migrate to default
usage plans. You'll be prompted with the Enable Usage Plans
option before using usage plans for the first time in the selected Region. When you
enable this option, you have default usage plans created for every unique API stage
that's associated with existing API keys. In the default usage plan, no throttle or
quota limits are set initially, and the associations between the API keys and API
stages are copied to the usage plans. The API behaves the same as before. However,
you must use the UsagePlan
apiStages
property to associate specified API stage values
(apiId
and stage
) with included API keys (via UsagePlanKey
), instead of using the ApiKey
stageKeys
property.
To check whether you've already migrated to default usage plans, use the get-account
CLI command. In the command output, the
features
list includes an entry of "UsagePlans"
when
usage plans are enabled.
You can also migrate your APIs to default usage plans by using the AWS CLI as
follows:
To migrate to default usage plans using the AWS CLI
-
Call this CLI command: update-account
.
-
For the cli-input-json
parameter, use the following
JSON:
[
{
"op": "add",
"path": "/features",
"value": "UsagePlans"
}
]
Create a usage plan
The following procedure describes how to create a usage plan.
- Old REST API console
We've redesigned the API Gateway console. The old console experience will no longer be available starting December 2023.
To create a usage plan
-
In the Amazon API Gateway main navigation pane, choose Usage
Plans, and then choose Create.
-
Under Create Usage Plan, do the following:
-
For Name, enter a name for your plan (for
example, Plan_A
).
-
For Description, enter a description for your
plan.
-
Select Enable throttling, and set
Rate (for example,
100
) and Burst (for
example, 200
).
-
Choose Enable quota, and set specify a value (for
example, 5000
) for a selected time interval
(for example, Month).
-
Choose Next.
-
To add a stage to the plan, do the following in the Associated
API Stages pane:
-
Choose Add API Stage.
-
Choose an API (for example, PetStore
) from
the API drop-down list.
-
Choose a stage (for example, Stage_1
) from
the Stage drop-down list.
-
Choose the checkmark icon to save.
-
To configure method
throttling, do the following:
-
Choose Configure Method Throttling.
-
Choose Add Resource/Method.
-
Choose the resource from the Resource
drop-down menu.
-
Choose the method from the Method drop-down
menu.
-
Set Rate (requests per second) (for example,
100
) and Burst (for
example, 200
).
-
Choose the checkmark icon to save.
-
Choose Close.
-
To add a key to the plan, do the following in the API
Keys tab:
-
To use an existing key, choose Add API Key to Usage
Plan.
-
For Name, enter a name for the key you want
to add (for example, MyFirstKey
).
-
Choose the checkmark icon to save.
-
As needed, repeat the preceding steps to add other existing API
keys to this usage plan.
Alternatively, to create a new API key and add it to the usage plan,
choose Create API Key and add to Usage Plan and
follow the instructions.
An API key can be associated with more than one usage plan. A usage
plan can be associated with more than one stage. However, a given API
key can only be associated with one usage plan for each stage of your
API.
-
To finish creating the usage plan, choose
Done.
-
If you want to add more API stages to the usage plan, choose Add
API Stage to repeat the preceding steps.
- New REST API console
-
To create a usage plan
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.
-
In the API Gateway main navigation pane, choose Usage
plans, and then choose Create usage plan.
-
For Name, enter a name.
-
(Optional) For Description, enter a description.
-
By default, usage plans enable throttling. Enter a Rate and a
Burst for your usage plan. Choose Throttling to turn off throttling.
-
By default, usage plans enable a quota for a time period. For Requests, enter the total number of
requests that a user can make in the time period of your usage plan. Choose Quota to turn off the quota.
-
Choose Create usage plan.
To add a stage to the usage plan
-
Select your usage plan.
-
Under the Associated stages tab, choose Add stage.
-
For API, select an API.
-
For Stage, select a stage.
-
(Optional) To turn on method-level throttling, do the following:
-
Choose Method-level throttling, and then choose Add method.
-
For Resource, select a resource from your API.
-
For Method, select a method from your API.
-
Enter a Rate and a
Burst for your usage plan.
-
Choose Add to usage plan.
To add a key to the usage plan
-
Under the Associated API keys tab, choose Add API key.
-
-
To associate an existing key to your usage plan, select Add existing key, and then select your existing key from the dropdown menu.
-
To create a new API key, select Create and add new key, and then create a new key. For more information on how to create a new key, see Create an API key.
-
Choose Add API key.
Test a usage plan
To test the usage plan, you can use an AWS SDK, AWS CLI, or a REST API client like
Postman. For an example of using Postman to test the usage plan, see Test usage plans.
Maintain a usage plan
Maintaining a usage plan involves monitoring the used and remaining quotas over a
given time period and, if needed, extending the remaining quotas by a specified
amount. The following procedures describe how to monitor quotas.
- Old REST API console
We've redesigned the API Gateway console. The old console experience will no longer be available starting December 2023.
To monitor used and remaining quotas
-
In the API Gateway main navigation pane, choose Usage
Plans.
-
Choose a usage plan from the list of usage plans.
-
From within the specified plan, choose API
Keys.
-
Choose an API key, and then choose Usage to view
Subscriber's Traffic from the plan you're
monitoring.
-
Optionally, choose Export, choose a
From date and a To date,
choose JSON
or CSV
for the
exported data format, and then choose Export.
The following example shows an exported file.
{
"thisPeriod": {
"px1KW6...qBazOJH": [
[
0,
5000
],
[
0,
5000
],
[
0,
10
]
]
},
"startDate": "2016-08-01",
"endDate": "2016-08-03"
}
The usage data in the example shows the daily usage data for an API
client, as identified by the API key (px1KW6...qBazOJH
),
between August 1, 2016 and August 3, 2016. Each daily usage data shows used
and remaining quotas. In this example, the subscriber hasn't used any
allotted quotas yet, and the API owner or administrator has reduced the
remaining quota from 5000 to 10 on the third day.
- New REST API console
-
To monitor used and remaining quotas
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.
-
In the API Gateway main navigation pane, choose Usage
plans.
-
Select a usage plan.
-
Choose the Associated API keys tab to see the number of request remaining for the time period for each key.
-
(Optional) Choose Export usage data, and then choose a
From date and a To date. Then
choose JSON or CSV for the
exported data format, and then choose Export.
The following example shows an exported file.
{
"thisPeriod": {
"px1KW6...qBazOJH": [
[
0,
5000
],
[
0,
5000
],
[
0,
10
]
]
},
"startDate": "2016-08-01",
"endDate": "2016-08-03"
}
The usage data in the example shows the daily usage data for an API
client, as identified by the API key (px1KW6...qBazOJH
),
between August 1, 2016 and August 3, 2016. Each daily usage data shows used
and remaining quotas. In this example, the subscriber hasn't used any
allotted quotas yet, and the API owner or administrator has reduced the
remaining quota from 5000 to 10 on the third day.
The following procedures describe how to modify quotas.
- Old REST API console
We've redesigned the API Gateway console. The old console experience will no longer be available starting December 2023.
To extend the remaining quotas
-
Repeat steps 1–3 of the previous procedure.
-
In the usage plan pane, choose Extension from the
usage plan window.
-
Enter a number for the Remaining request
quotas.
-
Choose Save.
- New REST API console
To extend the remaining quotas
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.
-
In the API Gateway main navigation pane, choose Usage
plans.
-
Select a usage plan.
-
Choose the Associated API keys tab to see the number of request remaining for the time period for each key.
-
Select an API key, and then choose Grant usage extension.
-
Enter a number for the Remaining requests quota. You can increase the renaming requests or decrease the remaining requests for the time period of your usage plan.
Choose Update quota.