Create, configure, and test usage plans with the API Gateway console - Amazon API Gateway
Migrate your API to default usage plans (if needed)Create a usage planTest a usage planMaintain a usage plan
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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 Amazon CLI as follows:

To migrate to default usage plans using the Amazon CLI

  1. Call this CLI command: update-account.

  2. 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.

To create a usage plan

  1. Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.

  2. In the API Gateway main navigation pane, choose Usage plans, and then choose Create usage plan.

  3. For Name, enter a name.

  4. (Optional) For Description, enter a description.

  5. By default, usage plans enable throttling. Enter a Rate and a Burst for your usage plan. Choose Throttling to turn off throttling.

  6. 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.

  7. Choose Create usage plan.

To add a stage to the usage plan

  1. Select your usage plan.

  2. Under the Associated stages tab, choose Add stage.

  3. For API, select an API.

  4. For Stage, select a stage.

  5. (Optional) To turn on method-level throttling, do the following:

    1. Choose Method-level throttling, and then choose Add method.

    2. For Resource, select a resource from your API.

    3. For Method, select a method from your API.

    4. Enter a Rate and a Burst for your usage plan.

  6. Choose Add to usage plan.

To add a key to the usage plan

  1. Under the Associated API keys tab, choose Add API key.

    1. To associate an existing key to your usage plan, select Add existing key, and then select your existing key from the dropdown menu.

    2. 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.

  3. Choose Add API key.

Test a usage plan

To test the usage plan, you can use an Amazon SDK, Amazon 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.

To monitor used and remaining quotas

  1. Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.

  2. In the API Gateway main navigation pane, choose Usage plans.

  3. Select a usage plan.

  4. Choose the Associated API keys tab to see the number of request remaining for the time period for each key.

  5. (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.

To extend the remaining quotas

  1. Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway.

  2. In the API Gateway main navigation pane, choose Usage plans.

  3. Select a usage plan.

  4. Choose the Associated API keys tab to see the number of request remaining for the time period for each key.

  5. Select an API key, and then choose Grant usage extension.

  6. 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.

  7. Choose Update quota.