Menu
Amazon API Gateway
Developer Guide

Set Up a Stage

This section walks you through the options to set up an API deployment stage in the API Gateway console.

Prerequisites

  • You must have a stage available in API Gateway. Follow the instructions in Create a Stage.

Set Up an API Deployment Stage with the API Gateway Console

  1. Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway.

  2. In the box that contains the name of the API for the stage where you want to specify settings, choose Stages.

  3. In the Stages pane, choose the name of the stage.

  4. To enable a cache for the API, on the Settings tab, in the Cache Settings area, select Enable API cache. Then, for Cache capacity, choose a cache size. You can use the default for other cache settings. Finally, choose Save Changes.

    Important

    By selecting this box, your AWS account may be charged for API caching.

    Tip

    To override enabled stage-level cache settings, expand the stage under the Stages secondary navigation pane, choose a method. Then back in the stage editor, choose Override for this method for Settings. In the ensuing Cache Settings area, clear Enable Method Cache or customize any other desired options, before choosing Save Changes. For more information about the method-level and other stage-level cache settings, see Enable API Caching.

  5. To generate code to call the API from Android, iOS, or JavaScript, you use the SDK Generation tab. For more information, see Generate and Call an SDK for an API in API Gateway.

  6. To enable Amazon CloudWatch Logs for all of the methods associated with this stage of this API Gateway API, do the following:

    1. On the Settings tab, in the CloudWatch Settings area, select Enable CloudWatch Logs.

      Tip

      To enable method-level CloudWatch settings, expand the stage under the Stages secondary navigation pane, choose each method of interest, and, back in the stage editor, choose Override for this method for Settings. In the ensuing CloudWatch Settings area, make sure to select Log to CloudWatch Logs and any other desired options, before choosing Save Changes.

      Important

      Your account will be charged for accessing method-level CloudWatch metrics, but not the API- or stage- level metrics.

    2. For Log level, choose ERROR to write only error-level entries to CloudWatch Logs, or choose INFO to include all ERROR events as well as extra informational events. No sensitive data will be logged unless the Log full requests/responses data option is selected.

    3. To write entries to CloudWatch Logs that contain full API call request and response information, select Log full requests/responses data.

    4. Choose Save Changes. The new settings will take effect after a new deployment.

      Important

      Whether you enable CloudWatch Logs for all or only some of the methods, you must also specify the ARN of an IAM role that enables API Gateway to write information to CloudWatch Logs on behalf of your IAM user. To do this, in the secondary navigation bar, in the first list next to the console home button, choose Settings. Then type the ARN of the IAM role in the CloudWatch Logging role ARN box. For common application scenarios, the IAM role could attach the managed policy of AmazonAPIGatewayPushToCloudWatchLogs, which contains the following access policy statement:

      Copy
      { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:PutLogEvents", "logs:GetLogEvents", "logs:FilterLogEvents" ], "Resource": "*" } ] }

      The IAM role must also contain the following trust relationship statement:

      Copy
      { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }

      To create the IAM role, you can adapt the instructions in "To create the Lambda invocation role and its policy" and "To create the Lambda execution role and its policy" in the Create Lambda Functions section of the Build an API to Expose a Lambda Function.

      For more information about CloudWatch, see the Amazon CloudWatch User Guide.

  7. To enable Amazon CloudWatch metrics for all of the methods associated with this API in API Gateway, in the Stage Editor pane, on the Settings tab, in the CloudWatch Settings area, select Enable CloudWatch metrics, and then choose Save Changes. The new settings will take effect after a new deployment.

    Important

    By selecting this box, your AWS account may be charged for using CloudWatch.

    Tip

    To enable CloudWatch metrics for only some methods, clear Enable CloudWatch metrics. In the Stages pane, choose each of the methods for which you want to enable CloudWatch metrics. For each method you choose, on the Settings tab for the method, choose Override for this method, and in the CloudWatch Settings area, select Enable CloudWatch metrics. Finally, choose Save Changes.

    For more information about CloudWatch, see the Amazon CloudWatch User Guide.

  8. To set a default throttle limit for all of the methods associated with this API in API Gateway, in the Stage Editor pane, on the Settings tab, in the Throttle Settings area, do the following, and then choose Save Changes:

    • For Burst Limit, type the absolute maximum number of times API Gateway will allow this method to be called per second. (The value of Burst Limit must be equal to or greater than the value of Rate.) The default setting is 1000 request per second.

    • For Rate, type the number of times API Gateway will allow this method to be called per second on average. (The value of Rate must be equal to or less than the value of Burst Limit.) The default setting is 500 request per second.

    Note

    • When creating a stage, if not supplied, API Gateway will enforce the default values of 1000 for Burst Limit and 500 for Rate in the stage settings.

    • In addition, API Gateway enforces overall account level throttling at the default values of 1000 for Burst Limitand 500 for Rate. If your require a higher level of throttling on your account, contact the AWS Support Center to request an increase.

    • API Gateway uses the token bucket algorithm, including average rate and burst size, for both account and method throttling.

  9. To change the stage to use a different deployment, in the Stage Editor pane, on the Change Deployment tab, choose the option button next to the deployment you want the stage to use, and then choose Change Deployment.