Setting up a stage using the API Gateway console - Amazon API Gateway

Setting up a stage using the API Gateway console

Create a new stage

After the initial deployment, you can add more stages and associate them with existing deployments. You can use the API Gateway console to create a new stage, or you can choose an existing stage while deploying an API. In general, you can add a new stage to an API deployment before redeploying the API. To create a new stage using the API Gateway console, follow these steps:

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

  2. Choose a REST API.

  3. In the main navigation pane, choose Stages under an API.

  4. From the Stages navigation pane, choose Create stage.

  5. For Stage name, enter a name, for example, prod.

    Note

    Stage names can only contain alphanumeric characters, hyphens, and underscores. Maximum length is 128 characters.

  6. (Optional). For Description, enter a stage description.

  7. For Deployment, select the date and time of the existing API deployment you want to associate with this stage.

  8. Under Additional settings, you can specify additional settings for your stage.

  9. Choose Create stage.

Update stage settings

After a successful deployment of an API, the stage is populated with default settings. You can use the console or the API Gateway REST API to change the stage settings, including API caching and logging. The following steps show you how to do so using the Stage editor of the API Gateway console.

Update stage settings using the API Gateway console

These steps assume that you've already deployed the API to a stage.

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

  2. Choose a REST API.

  3. In the main navigation pane, choose Stages under an API.

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

  5. In the Stage details section, choose Edit.

  6. (Optional) For Stage description, edit the description.

  7. For Additional settings, you modify the following settings:

    Cache settings

    To enable API caching for the stage, turn on Provision API cache. Then configure the Default method-level caching, Cache capacity, Encrypt cache data, Cache time-to-live (TTL), as well as any requirements for per-key cache invalidation.

    Caching is not active until you turn on the default method-level caching or turn on the method-level cache for a specific method.

    For more information about cache settings, see Enabling API caching to enhance responsiveness.

    Note

    If you enable API caching for an API stage, your AWS account might be charged for API caching. Caching isn't eligible for the AWS Free Tier.

    Throttling settings

    To set stage-level throttling targets for all of the methods associated with this API, turn on Throttling.

    For Rate, enter a target rate. This is the rate, in requests per second, that tokens are added to the token bucket. The stage-level rate must not be more than the account-level rate as specified in API Gateway quotas for configuring and running a REST API.

    For Burst, enter a target burst rate. The burst rate, is the capacity of the token bucket. This allows more requests through for a period of time than the target rate. This stage-level burst rate must not be more than the account-level burst rate as specified in API Gateway quotas for configuring and running a REST API.

    Note

    Throttling rates are not hard limits, and are applied on a best-effort basis. In some cases, clients can exceed the targets that you set. Don’t rely on throttling to control costs or block access to an API. Consider using AWS Budgets to monitor costs and AWS WAF to manage API requests.

    Firewall and certificate settings

    To associate an AWS WAF web ACL with the stage, select a web ACL from the Web ACL dropdown list. If desired, choose Block API Request if WebACL cannot be evaluated (Fail- Close).

    To select a client certificate for your stage, select a certificate from the Client certificate dropdown menu.

  8. Choose Save.

  9. To enable Amazon CloudWatch Logs for all of the methods associated with this stage of this API Gateway API, in the Logs and tracing section, choose Edit.

    Note

    To enable CloudWatch Logs, you must also specify the ARN of an IAM role that enables API Gateway to write information to CloudWatch Logs on behalf of your user. To do so, choose Settings from the APIs main navigation pane. Then, for CloudWatch log role, enter the ARN of an IAM role.

    For common application scenarios, the IAM role could attach the managed policy of AmazonAPIGatewayPushToCloudWatchLogs, which contains the following access policy statement:

    { "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:

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

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

  10. Select a logging level from the CloudWatch Logs dropdown menu. The logging levels are the following:

    • Off – Logging is not turned on for this stage.

    • Errors only – Logging is enabled for errors only.

    • Errors and info logs – Logging is enabled for all events.

    • Full request and response logs – Detailed logging is enabled for all events. This can be useful to troubleshoot APIs, but can result in logging sensitive data.

      Note

      We recommend that you don't use Full request and response logs for production APIs.

  11. Select Detailed metrics to have API Gateway report to CloudWatch the API metrics of API calls, Latency, Integration latency, 400 errors, and 500 errors. For more information about CloudWatch, see the Basic monitoring and detailed monitoring in the Amazon CloudWatch User Guide.

    Important

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

  12. To enable access logging to a destination, turn on Custom access logging.

  13. For Access log destination ARN, enter the ARN of a log group or a Firehose stream.

    The ARN format for Firehose is arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}. The name of your Firehose stream must be amazon-apigateway-{your-stream-name}.

  14. In Log format, enter a log format. To learn more about example log formats, see CloudWatch log formats for API Gateway.

  15. To enable AWS X-Ray tracing for the API stage, select X-Ray tracing. For more information, see Tracing user requests to REST APIs using X-Ray.

  16. Choose Save changes. Redeploy your API for the new settings to take effect.

Override stage-level settings

You can override the following enabled stage-level settings. Some of these options might result in additional charges to your AWS account.

Override stage-level settings using the API Gateway console

To override stage-level settings using the API Gateway console
  1. To configure method overrides, expand the stage under the secondary navigation pane, and then choose a method.

    
          Expand the stage under the secondary navigation pane, and choose a method.
  2. For Method overrides, choose Edit.

  3. To turn on method-level CloudWatch settings, for CloudWatch Logs, select a logging level.

  4. To turn on method-level detailed metrics, select Detailed metrics. Your account is charged for accessing method-level CloudWatch metrics, but not the API-level or stage-level metrics.

  5. To turn on method-level throttling, select Throttling. Enter the appropriate method-level options. To learn more about throttling, see Throttle API requests for better throughput.

  6. To configure the method-level cache, select Enable method cache. If you change the default method-level caching setting in the Stage details, it doesn't affect this setting.

  7. Choose Save.

Delete a stage

When you no longer need a stage, you can delete it to avoid paying for unused resources. The following steps show you how to use the API Gateway console to delete a stage.

Warning

Deleting a stage might cause part or all of the corresponding API to be unusable by API callers. Deleting a stage cannot be undone, but you can recreate the stage and associate it with the same deployment.

Delete a stage using the API Gateway console

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

  2. Choose a REST API.

  3. In the main navigation pane, choose Stages.

  4. In the Stages pane, choose the stage you want to delete, and then choose Stage actions, Delete stage.

  5. When you're prompted, enter confirm, and then choose Delete.