# Deploy REST APIs in API Gateway
After creating your API, you must deploy it to make it callable by your users.
To deploy an API, you create an API deployment and associate it with a stage. A stage is a logical reference to a lifecycle state of your API (for example, `dev`, `prod`, `beta`, `v2`). API stages are identified by the API ID and stage name. They're included in the URL that you use to invoke the API. Each stage is a named reference to a deployment of the API and is made available for client applications to call.
**Important**
Every time you update an API, you must redeploy the API to an existing stage or to a new stage. Updating an API includes modifying routes, methods, integrations, authorizers, resource policies, and anything else other than stage settings.
As your API evolves, you can continue to deploy it to different stages as different versions of the API. You can also deploy your API updates as a [canary release deployment](canary-release.md). This enables your API clients to access, on the same stage, the production version through the production release, and the updated version through the canary release.
To call a deployed API, the client submits a request against an API's URL. The URL is determined by an API's protocol (HTTP(S) or (WSS)), hostname, stage name, and (for REST APIs) resource path. The hostname and the stage name determine the API's base URL.
Using the API's default domain name, the base URL of a REST API (for example) in a given stage (`{stageName}`) is in the following format:
```
https://{restapi-id}.execute-api.{region}.amazonaws.com/{stageName}
```
To make the API's default base URL more user-friendly, you can create a custom domain name (for example, `api.example.com`) to replace the default hostname of the API. To support multiple APIs under the custom domain name, you must map an API stage to a base path.
With a custom domain name of `{api.example.com}` and the API stage mapped to a base path of (`{basePath}`) under the custom domain name, the base URL of a REST API becomes the following:
```
https://{api.example.com}/{basePath}
```
For each stage, you can optimize API performance by adjusting the default account-level request throttling limits and enabling API caching. You can also enable logging for API calls to CloudTrail or CloudWatch, and can select a client certificate for the backend to authenticate the API requests. In addition, you can override stage-level settings for individual methods and define stage variables to pass stage-specific environment contexts to the API integration at runtime.
Stages enable robust version control of your API. For example, you can deploy an API to a `test` stage and a `prod` stage, and use the `test` stage as a test build and use the `prod` stage as a stable build. After the updates pass the test, you can promote the `test` stage to the `prod` stage. The promotion can be done by redeploying the API to the `prod` stage or updating a stage variable value from the stage name of `test` to that of `prod`.
In this section, we discuss how to deploy an API by using the [API Gateway console](https://console.aws.amazon.com/apigateway) or calling the [API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/api/). To use other tools, see the documentation of the [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/) or an [AWS SDK](https://aws.amazon.com/developer/tools/#sdk).
**Topics**
+ [
# Create a deployment for a REST API in API Gateway
](set-up-deployments.md)
+ [
# Set up a stage for a REST API in API Gateway
](set-up-stages.md)
+ [
# Set up an API Gateway canary release deployment
](canary-release.md)
+ [
# Updates to REST APIs that require redeployment
](updating-api.md)
# Create a deployment for a REST API in API Gateway
In API Gateway, a REST API deployment is represented by a [Deployment](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) resource. It's similar to an executable of an API that is represented by a [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) resource.
For the client to call your API, you must create a deployment and associate a stage with it. A stage is represented by a [Stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) resource. It represents a snapshot of the API, including methods, integrations, models, mapping templates, and Lambda authorizers (formerly known as custom authorizers). When you update the API, you can redeploy the API by associating a new stage with the existing deployment. We discuss creating a stage in [Set up a stage for a REST API in API Gateway](set-up-stages.md).
**Topics**
+ [
## Create a deployment
](#create-deployment)
+ [
## Next steps for your API deployment
](#apigateway-deployment-next-steps)
## Create a deployment
The following procedures show how to create a deployment for a REST API.
------
#### [ AWS Management Console ]
You must have created a REST API before deploying it for the first time. For more information, see [Develop REST APIs in API Gateway](rest-api-develop.md).
The API Gateway console lets you deploy an API by creating a deployment and associating it with a new or existing stage.
1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. In the **APIs** navigation pane, choose the API you want to deploy.
1. In the **Resources** pane, choose **Deploy API**.
1. For **Stage**, select from the following:
1. To create a new stage, select **New stage**, and then enter a name in **Stage name**. Optionally, you can provide a description for the deployment in **Deployment description**.
1. To choose an existing stage, select the stage name from the dropdown menu. You might want to provide a description of the new deployment in **Deployment description**.
1. To create a deployment that is not associated with a stage, select **No stage**. Later, you can associate this deployment with a stage.
1. Choose **Deploy**.
------
#### [ AWS CLI ]
When you create a deployment, you instantiate the [Deployment](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) resource.
The following [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) command creates a new deployment:
```
aws apigateway create-deployment --rest-api-id rest-api-id
```
You can't call the API until you associate this deployment with a stage. With an existing stage, you can do this by updating the stage's [deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) property with the newly created deployment ID. The following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) command updates the stage with a new deployment. In the console, this is called the **Active deployment**.
```
aws apigateway update-stage \
--rest-api-id rest-api-id \
--stage-name 'stage-name' \
--patch-operations op='replace',path='/deploymentId',value='deployment-id'
```
When you create your deployment, you can also associate it with a new stage at the same time. The following [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) command creates a new deployment and associates it with a new stage called `beta`:
```
aws apigateway create-deployment \
--rest-api-id rest-api-id \
--stage-name beta
```
------
To redeploy an API, perform the same steps. You can reuse the same stage.
## Next steps for your API deployment
The following are next steps for your API deployment.
Modify stage settings
After an API is deployed, you can modify the stage settings to enable or disable the API cache, logging, or request throttling. You can also choose a client certificate for the backend to authenticate API Gateway and set stage variables to pass deployment context to the API integration at runtime. For more information, see [Modify stage settings](set-up-stages.md#how-to-stage-settings)
After modifying stage settings, you must redeploy the API for the changes to take effect.
If the updated settings, such as enabling logging, requires a new IAM role, you can add the required IAM role without redeploying the API. However, it might take a few minutes before the new IAM role takes effect. Before that happens, traces of your API calls are not logged even if you have enabled the logging option.
Choose different deployment-stage combinations
Because a deployment represents an API snapshot and a stage defines a path into a snapshot, you can choose different deployment-stage combinations to control how users call into different versions of the API. This is useful, for example, when you want to roll back API state to a previous deployment or to merge a 'private branch' of the API into the public one.
The following procedure shows how to do this using the **Stage Editor** in the API Gateway console. It is assumed that you must have deployed an API more than once.
1. If you're not already on the **Stages** pane, in the main navigation pane, choose **Stages**.
1. Select the stage you want to update.
1. On the **Deployment history** tab, select the deployment you want the stage to use.
1. Choose **Change active deployment**.
1. Confirm you want to change the active deployment and choose **Change active deployment** in the **Make active deployment** dialog box.
Pass deployment-specific data to your API.
For a deployment, you can set or modify stage variables to pass deployment-specific data to the API integration at runtime. You can do this on the **Stage Variables** tab in the **Stage Editor**. For more information, see instructions in [Use stage variables for a REST API in API Gateway](stage-variables.md).
# Set up a stage for a REST API in API Gateway
A stage is a named reference to a deployment, which is a snapshot of the API. You use a [Stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) to manage and optimize a particular deployment. For example, you can configure stage settings to enable caching, customize request throttling, configure logging, define stage variables, or attach a canary release for testing. The following section shows how to create and configure your stage.
## 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](https://console.aws.amazon.com/apigateway).
1. Choose a REST API.
1. In the main navigation pane, choose **Stages** under an API.
1. From the **Stages** navigation pane, choose **Create stage**.
1. 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.
1. (Optional). For **Description**, enter a stage description.
1. For **Deployment**, select the date and time of the existing API deployment you want to associate with this stage.
1. Under **Additional settings**, you can specify additional settings for your stage.
1. Choose **Create stage**.
## Modify 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. If you've modified the default endpoint of your REST API, when you update a stage, the modification is propagated to all stages of your API. The following steps show you how to do so using the **Stage editor** of the API Gateway console.
1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choose a REST API.
1. In the main navigation pane, choose **Stages** under an API.
1. In the **Stages** pane, choose the name of the stage.
1. In the **Stage details** section, choose **Edit**.
1. (Optional) For **Stage description**, edit the description.
1. 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 [Cache settings for REST APIs in API Gateway](api-gateway-caching.md).
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](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits) rate as specified in [Quotas for configuring and running a REST API in API Gateway](api-gateway-execution-service-limits-table.md).
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](api-gateway-request-throttling.md#apig-request-throttling-account-level-limits) burst rate as specified in [Quotas for configuring and running a REST API in API Gateway](api-gateway-execution-service-limits-table.md).
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](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) to monitor costs and [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) 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.
1. Choose **Continue**.
1. Review your changes and choose **Save changes**.
1. 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](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html).
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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)*.
1. 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.
1. Select **Data tracing** to have API Gateway report to CloudWatch the data trace logging for your stage. This can be useful to troubleshoot APIs, but can result in logging sensitive data.
**Note**
We recommend that you don't use **Data tracing** for production APIs.
1. 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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-metrics-basic-detailed.html) 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.
1. To enable access logging to a destination, turn on **Custom access logging**.
1. 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}`.
1. In **Log format**, enter a log format. To learn more about example log formats, see [CloudWatch log formats for API Gateway](set-up-logging.md#apigateway-cloudwatch-log-formats).
1. To enable [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) tracing for the API stage, select ** X-Ray tracing**. For more information, see [Trace user requests to REST APIs using X-Ray in API Gateway](apigateway-xray.md).
1. Choose **Save changes**. Redeploy your API for the new settings to take effect.
## Override stage-level settings
After you customize the stage-level settings, you can override them for each API method. Some of these options might result in additional charges to your AWS account.
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.\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/method-override-view-new-console.png)
1. For **Method overrides**, choose **Edit**.
1. To turn on method-level CloudWatch settings, for **CloudWatch Logs**, select a logging level.
1. To turn on data trace logging for your method, select **Data tracing**.
**Note**
We recommend that you don't use **Data tracing** for production APIs.
1. 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.
1. To turn on method-level throttling, select **Throttling**. Enter the appropriate method-level options. To learn more about throttling, see [Throttle requests to your REST APIs for better throughput in API Gateway](api-gateway-request-throttling.md).
1. 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.
1. Choose **Save**.
# Add an API Gateway REST API as a target for Amazon Bedrock AgentCore Gateway
An Amazon Bedrock AgentCore Gateway provides AI agent developers a secure way to expose your API Gateway REST APIs as Model Context Protocol (MCP)-compatible tools. AgentCore Gateway uses targets to define tools. When you add your stage as a target, your Gateway becomes a single MCP URL that enables access to the tools for an agent. For more information, see [API Gateway REST API stages as targets](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-api-gateway.html) in the *Amazon Bedrock AgentCore Gateway Developer Guide*.
API Gateway targets connect your AgentCore Gateway to stages of your REST APIs. You can include the entire stage as a target, or select resources. After you create the API Gateway target, AgentCore Gateway translates incoming MCP requests into HTTP requests and handles the response formatting. MCP clients can retrieve API documentation using the `tools/list` method and invoke APIs using the `tools/call` method.
## Considerations
The following considerations might impact your use adding a stage as a target to a AgentCore Gateway:
+ You must already have a AgentCore Gateway.
+ Only public REST APIs are supported.
+ The default endpoint of your API cannot be disabled.
+ Every method of your API must either have an [operation name](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html#apigw-PutMethod-request-operationName) defined for it, or your need to create a name override when you add your stage as a target. This name is used as the tool name that agents use to interact with your method.
+ You can use `API_KEY`, `NO_AUTH`, or `GATEWAY_IAM_ROLE` credential provider types for Outbound Auth to allow your Gateway to access your API. The `API_KEY` credential provider is defined by AgentCore Gateway. You can use your existing API Gateway API key. For more information, see [Setting up Outbound Auth](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-outbound-auth.html).
+ If you use a Amazon Cognito user pool or Lambda authorizer to control access to your API, MCP clients cannot access it.
+ Your API must be in the same account and Region as your AgentCore Gateway.
## Add a stage of an API as a target for a AgentCore Gateway
The following procedure shows how to add a stage of an API as a target for a AgentCore Gateway.
**To add a stage of an API as a target for a AgentCore Gateway**
1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choose a REST API that's deployed to a stage.
1. In the main navigation pane, choose **Stages**.
1. Choose **Stage actions**, and then choose **Create MCP target**.
1. For **AgentCore Gateway**, select an AgentCore Gateway.
1. For **Target name**, enter a target name.
1. For **Target description**, enter a description.
1. Keep the provided API and stage.
1. For **Select API resources**, select the resources of your API that agents using your AgentCore Gateway can access.
If you don't select a resource, an agent cannot view the documentation or invoke the endpoint.
1. The combination of the resource and the method are the operations for the tool. If your operation does not have a name, create a name override.
You can also define an operation name for a method when you create it.
1. For **Outbound Auth configuration**, choose either **IAM Role **, **No authorization** or **API key**.
1. Choose **Create target**.
To view all the AgentCore Gateways that have access to your APIs, choose the **MCP targets** section in the main navigation pane. In this section, you can create a MCP target for any API in your Region deployed to a stage. Choose **Create MCP target** and follow the previous steps.
You can also view the available tools for your target and edit your target in the AgentCore Gateway console. For more information, see [Add targets to an existing AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building-adding-targets.html).
# 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.
1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Choose a REST API.
1. In the main navigation pane, choose **Stages**.
1. In the **Stages** pane, choose the stage you want to delete, and then choose **Stage actions**, **Delete stage**.
1. When you're prompted, enter **confirm**, and then choose **Delete**.
# Set up tags for an API stage in API Gateway
In API Gateway, you can add a tag to an API stage, remove the tag from the stage, or view the tag. To do this, you can use the API Gateway console, the AWS CLI/SDK, or the API Gateway REST API.
A stage can also inherit tags from its parent REST API. For more information, see [Tag inheritance in the Amazon API Gateway V1 API](apigateway-tagging-supported-resources.md#apigateway-tagging-inheritance).
For more information about tagging API Gateway resources, see [Tagging your API Gateway resources](apigateway-tagging.md).
**Topics**
+ [
## Set up tags for an API stage using the API Gateway console
](#set-up-tags-using-console)
+ [
## Set up tags for an API stage using the AWS CLI
](#set-up-tags-using-cli)
+ [
## Set up tags for an API stage using the API Gateway REST API
](#set-up-tags-using-api)
## Set up tags for an API stage using the API Gateway console
The following procedure describes how to set up tags for an API stage.
**To set up tags for an API stage by using the API Gateway console**
1. Sign in to the API Gateway console.
1. Choose an existing API, or create a new API that includes resources, methods, and the corresponding integrations.
1. Choose a stage or deploy the API to a new stage.
1. In the main navigation pane, choose **Stages**.
1. Choose the **Tags** tab. You might need to choose the right arrow button to show the tab.
1. Choose **Manage tags**.
1. In the **Tag Editor**, choose **Add tag**. Enter a tag key (for example, `Department`) in the **Key** field, and enter a tag value (for example, `Sales`) in the **Value** field. Choose **Save** to save the tag.
1. If needed, repeat step 5 to add more tags to the API stage. The maximum number of tags per stage is 50.
1. To remove an existing tag from the stage, choose **Remove**.
1. If the API has been deployed previously in the API Gateway console, you need to redeploy it for the changes to take effect.
## Set up tags for an API stage using the AWS CLI
You can set up tags for an API stage using the AWS CLI using the [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) command or the [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html) command. You can delete one or more tags from an API stage using the [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html) command.
The following [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) command adds a tag when creating a `test` stage:
```
aws apigateway create-stage --rest-api-id abc1234 --stage-name test --description 'Testing stage' --deployment-id efg456 --tag Department=Sales
```
The following [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/tag-resource.html) command adds a tag to a `prod` stage:
```
aws apigateway tag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/prod --tags Department=Sales
```
The following [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/untag-resource.html) command removes the `Department=Sales` tag from the `test` stage:
```
aws apigateway untag-resource --resource-arn arn:aws:apigateway:us-east-2::/restapis/abc123/stages/test --tag-keys Department
```
## Set up tags for an API stage using the API Gateway REST API
You can set up tags for an API stage using the API Gateway REST API by doing one of the following:
+ Call [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html) to tag an API stage.
+ Call [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html) to delete one or more tags from an API stage.
+ Call [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) to add one or more tags to an API stage that you're creating.
You can also call [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html) to describe tags in an API stage.
### Tag an API stage
After you deploy an API (`m5zr3vnks7`) to a stage (`test`), tag the stage by calling [https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_TagResource.html). The required stage Amazon Resource Name (ARN) (`arn:aws:apigateway:us-east-1::/restapis/m5zr3vnks7/stages/test`) must be URL encoded (`arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest`).
```
PUT /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest
{
"tags" : {
"Department" : "Sales"
}
}
```
You can also use the previous request to update an existing tag to a new value.
You can add tags to a stage when calling [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html) to create the stage:
```
POST /restapis//stages
{
"stageName" : "test",
"deploymentId" : "adr134",
"description" : "test deployment",
"cacheClusterEnabled" : "true",
"cacheClusterSize" : "500",
"variables" : {
"sv1" : "val1"
},
"documentationVersion" : "test",
"tags" : {
"Department" : "Sales",
"Division" : "Retail"
}
}
```
### Untag an API stage
To remove the `Department` tag from the stage, call [https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UntagResource.html):
```
DELETE /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftest?tagKeys=Department
Host: apigateway.us-east-1.amazonaws.com
Authorization: ...
```
To remove more than one tag, use a comma-separated list of tag keys in the query expression—for example, `?tagKeys=Department,Division,…`.
### Describe tags for an API stage
To describe existing tags on a given stage, call [https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html](https://docs.aws.amazon.com/apigateway/latest/api/API_GetTags.html):
```
GET /tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags
Host: apigateway.us-east-1.amazonaws.com
Authorization: ...
```
The successful response is similar to the following:
```
200 OK
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-tags-{rel}.html",
"name": "tags",
"templated": true
},
"tags:tag": {
"href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags"
},
"tags:untag": {
"href": "/tags/arn%3Aaws%3Aapigateway%3Aus-east-1%3A%3A%2Frestapis%2Fm5zr3vnks7%2Fstages%2Ftags{?tagKeys}",
"templated": true
}
},
"tags": {
"Department": "Sales"
}
}
```
# Use stage variables for a REST API in API Gateway
Stage variables are key-value pairs that you can define as configuration attributes associated with a deployment stage of a REST API. They act like environment variables and can be used in your API setup and mapping templates. With deployment stages in API Gateway, you can manage multiple release stages for each API and use stage variables you can configure an API deployment stage to interact with different backend endpoints.
Stage variables are not intended to be used for sensitive data, such as credentials. To pass sensitive data to integrations, use an AWS Lambda authorizer. You can pass sensitive data to integrations in the output of the Lambda authorizer. To learn more, see [Output from an API Gateway Lambda authorizer](api-gateway-lambda-authorizer-output.md).
## Use cases for stage variables
The following are use cases for your stage variables.
**Specify a different backend endpoint**
Your API can pass a `GET` request as an HTTP proxy to the backend web host. You can use a stage variable so that when API callers invoke your production endpoint, API Gateway calls `example.com`. Then, when API callers invoke the beta stage, API Gateway calls a different web host, such as `beta.example.com`. Similarly, stage variables can be used to specify a different AWS Lambda function name for each stage in your API. You can't use a stage variable to set a different integration endpoint, such as pointing the `GET` request to an HTTP proxy integration in one stage and a Lambda proxy integration in another stage.
When specifying a Lambda function name as a stage variable value, you must configure the permissions on the Lambda function manually. When you specify a Lambda function in the API Gateway console, a AWS CLI command will pop-up to configure the proper permissions. You can also use the following AWS CLI command to do this.
```
aws lambda add-permission --function-name "arn:aws:lambda:us-east-2:123456789012:function:my-function" --source-arn "arn:aws:execute-api:us-east-2:123456789012:api_id/*/HTTP_METHOD/resource" --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
**Pass information using mapping templates**
You can access stage variables in the mapping templates, or pass configuration parameters to your AWS Lambda or HTTP backend. For example, you might want to reuse the same Lambda function for multiple stages in your API, but the function should read data from a different Amazon DynamoDB table depending on the stage. In the mapping templates that generate the request for the Lambda function, you can use stage variables to pass the table name to Lambda.
To use a stage variable, you first configure a stage variable, and then you assign it a value. For example, to customize the HTTP integration endpoint, first create the `url` stage variable, and then in your API's integration request, enter the stage variable value, **http://\$1\$1stageVariables.url\$1**. This value tells API Gateway to substitute your stage variable `${}` at runtime, depending on which stage your API is running. For more information, see [Set up stage variables for REST APIs in API Gateway](how-to-set-stage-variables-aws-console.md).
# Set up stage variables for REST APIs in API Gateway
This section shows how to set up various stage variables for two deployment stages of a sample API by using the Amazon API Gateway console. To understand how to use stage variables in API Gateway, we recommend that you follow all procedures in this section.
## Prerequisites
Before you begin, make sure the following prerequisites are met:
+ You must have an API available in API Gateway. Follow the instructions in [Develop REST APIs in API Gateway](rest-api-develop.md).
+ You must have deployed the API at least once. Follow the instructions in [Deploy REST APIs in API Gateway](how-to-deploy-api.md).
+ You must have created the first stage for a deployed API. Follow the instructions in [Create a new stage](set-up-stages.md#how-to-create-stage-console).
## Invoke an HTTP endpoint through an API with a stage variable
This procedure describes how to create a stage variable for an HTTP endpoint and two stages for your API. In addition, you create the stage variables, `url`, `stageName`, and `function` that are used in the following procedures in this section.
**To invoke an HTTP endpoint through an API with a stage variable**
1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Create an API, and then create a `GET` method on the API's root resource. Set the integration type to **HTTP** and set the **Endpoint URL** to **http://\$1\$1stageVariables.url\$1**.
1. Deploy the API to a new stage named **beta**.
1. In the main navigation pane, choose **Stages**, and then select the **beta** stage.
1. On the **Stage variables** tab, choose **Edit**.
1. Choose **Add stage variable**.
1. For **Name**, enter **url**. For **value**, enter **httpbin.org/get**.
1. Choose **Add stage variable**, and then do the following:
For **Name**, enter **stageName**. For **value**, enter **beta**.
1. Choose **Add stage variable**, and then do the following:
For **Name**, enter **function**. For **value**, enter **HelloWorld**.
1. Choose **Save**.
1. Now create a second stage. From the **Stages** navigation pane, choose **Create stage**. For **Stage name**, enter **prod**. Select a recent deployment from **Deployment**, and then choose **Create stage**.
1. As with the **beta** stage, set the same three stage variables (**url**, **stageName**, and **function**) to different values (**petstore-demo-endpoint.execute-api.com/petstore/pets**, **prod**, and **HelloEveryone**), respectively.
1. In the **Stages** navigation pane, choose **beta**. Under **Stage details**, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in a web browser. This starts the **beta** stage `GET` request on the root resource of the API.
**Note**
The **Invoke URL** link points to the root resource of the API in its **beta** stage. Entering the URL in a web browser calls the **beta** stage `GET` method on the root resource. If methods are defined on child resources and not on the root resource itself, entering the URL in a web browser returns a `{"message":"Missing Authentication Token"}` error response. In this case, you must append the name of a specific child resource to the **Invoke URL** link.
1. The response you get from the **beta** stage `GET` request is shown next. You can also verify the result by using a browser to navigate to **http://httpbin.org/get**. This value was assigned to the `url` variable in the **beta** stage. The two responses are identical.
1. In the **Stages** navigation pane, choose the **prod** stage. Under **Stage details**, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in a web browser. This starts the **prod** stage `GET` request on the root resource of the API.
1. The response you get from the **prod** stage `GET` request is shown next. You can verify the result by using a browser to navigate to **http://petstore-demo-endpoint.execute-api.com/petstore/pets**. This value was assigned to the `url` variable in the **prod** stage. The two responses are identical.
## Pass stage-specific metadata into an HTTP backend
This procedure describes how to use a stage variable value in a query parameter expression to pass stage-specific metadata into an HTTP backend. We will use the `stageName` stage variable declared in the previous procedure.
**To pass stage-specific metadata into an HTTP backend**
1. In the **Resource** navigation pane, choose the **GET** method.
To add a query string parameter to the method's URL, choose the **Method request** tab, and then in the **Method request settings** section, choose **Edit**.
1. Choose **URL query string parameters** and do the following:
1. Choose **Add query string**.
1. For **Name**, enter **stageName**.
1. Keep **Required** and **Caching** turned off.
1. Choose **Save**.
1. Choose the **Integration request** tab, and then in the **Integration request settings** section, choose **Edit**.
1. For **Endpoint URL**, append **?stageName=\$1\$1stageVariables.stageName\$1** to the previously defined URL value, so the entire **Endpoint URL** is **http://\$1\$1stageVariables.url\$1?stageName=\$1\$1stageVariables.stageName\$1**.
1. Choose **Deploy API** and select the **beta** stage.
1. In the main navigation pane, choose **Stages**. In the **Stages** navigation pane, choose **beta**. Under **Stage details**, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in a web browser.
**Note**
We use the beta stage here because the HTTP endpoint (as specified by the `url` variable "http://httpbin.org/get") accepts query parameter expressions and returns them as the `args` object in its response.
1. You get the following response. Notice that `beta`, assigned to the `stageName` stage variable, is passed in the backend as the `stageName` argument.
![\[Response from the API's GET method with an HTTP endpoint using the url stage variable.\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/stageVariables-new-console-invoke-beta-stage-with-url-and-stageName-response.png)
## Invoke a Lambda function through an API with a stage variable
This procedure describes how to use a stage variable to call a Lambda function as a backend of your API. You use the `function` stage variable declared in [Invoke an HTTP endpoint through an API with a stage variable](#how-to-set-stage-variables-aws-console-http-endpoint).
When setting a Lambda function as the value of a stage variable, use the function's local name, possibly including its alias or version specification, as in **HelloWorld**, **HelloWorld:1** or **HelloWorld:alpha**. Do not use the function's ARN (for example, **arn:aws:lambda:us-east-1:123456789012:function:HelloWorld**). The API Gateway console assumes the stage variable value for a Lambda function as the unqualified function name and expands the given stage variable into an ARN.
**To invoke a Lambda function through an API with a stage variable**
1. Create a Lambda function named **HelloWorld** using the default Node.js runtime. The code must contain the following:
```
export const handler = function(event, context, callback) {
if (event.stageName)
callback(null, 'Hello, World! I\'m calling from the ' + event.stageName + ' stage.');
else
callback(null, 'Hello, World! I\'m not sure where I\'m calling from...');
};
```
For more information on how to create a Lambda function, see [Getting started with the REST API console](getting-started-rest-new-console.md#getting-started-rest-new-console-create-function).
1. In the **Resources** pane, select **Create resource**, and then do the following:
1. For **Resource path**, select **/**.
1. For **Resource name**, enter **lambdav1**.
1. Choose **Create resource**.
1. Choose the **/lambdav1** resource, and then choose **Create method**.
Then, do the following:
1. For **Method type**, select **GET**.
1. For **Integration type**, select **Lambda function**.
1. Keep **Lambda proxy integration** turned off.
1. For **Lambda function**, enter `${stageVariables.function}`.
![\[Create a GET method integrated with a Lambda function as specified by the function stage variable.\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/stageVariables-new-console-create-lambda-get-method.png)
**Tip**
When prompted with the **Add permission command**, copy the [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) command. Run the command on each Lambda function that will be assigned to the `function` stage variable. For example, if the `$stageVariables.function` value is `HelloWorld`, run the following AWS CLI command:
```
aws lambda add-permission --function-name arn:aws:lambda:us-east-1:account-id:function:HelloWorld --source-arn arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/lambdav1 --principal apigateway.amazonaws.com --statement-id statement-id-guid --action lambda:InvokeFunction
```
Failing to do so results in a `500 Internal Server Error` response when invoking the method. Replace `${stageVariables.function}` with the Lambda function name that is assigned to the stage variable.
![\[AWS CLI command to add permission to the Lambda function to be invoked by the method you created.\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/stageVariables-new-console-add-permission-to-lambda-function.png)
1. Choose **Create method**.
1. Deploy the API to both the **prod** and **beta** stages.
1. In the main navigation pane, choose **Stages**. In the **Stages** navigation pane, choose **beta**. Under **Stage details**, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in a web browser. Append **/lambdav1** to the URL before you press enter.
You get the following response.
```
"Hello, World! I'm not sure where I'm calling from..."
```
## Pass stage-specific metadata to a Lambda function through a stage variable
This procedure describes how to use a stage variable to pass stage-specific configuration metadata into a Lambda function. You create a `POST` method and an input mapping template to generate payload using the `stageName` stage variable you declared earlier.
**To pass stage-specific metadata to a Lambda function through a stage variable**
1. Choose the **/lambdav1** resource, and then choose **Create method**.
Then, do the following:
1. For **Method type**, select **POST**.
1. For **Integration type**, select **Lambda function**.
1. Keep **Lambda proxy integration** turned off.
1. For **Lambda function**, enter `${stageVariables.function}`.
1. When prompted with the **Add permission command**, copy the the [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) command. Run the command on each Lambda function that will be assigned to the `function` stage variable.
1. Choose **Create method**.
1. Choose the **Integration request** tab, and then in the **Integration request settings** section, choose **Edit**.
1. Choose **Mapping templates**, and then choose **Add mapping template**.
1. For **Content type**, enter **application/json**.
1. For **Template body**, enter the following template:
```
#set($inputRoot = $input.path('$'))
{
"stageName" : "$stageVariables.stageName"
}
```
**Note**
In a mapping template, a stage variable must be referenced within quotes (as in `"$stageVariables.stageName"` or `"${stageVariables.stageName}"`). In other places, it must be referenced without quotes (as in `${stageVariables.function}`).
1. Choose **Save**.
1. Deploy the API to both the **beta** and **prod** stages.
1. To use a REST API client to pass stage-specific metadata, do the following:
1. In the **Stages** navigation pane, choose **beta**. Under **Stage details**, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in the input field of a REST API client. Append **/lambdav1** before you submit your request.
You get the following response.
```
"Hello, World! I'm calling from the beta stage."
```
1. In the **Stages** navigation pane, choose **prod**. Under **Stage details**, choose the copy icon to copy your API's invoke URL, and then enter your API's invoke URL in the input field of a REST API client. Append **/lambdav1** before you submit your request.
You get the following response.
```
"Hello, World! I'm calling from the prod stage."
```
1. To use the **Test** feature to pass stage-specific metadata, do the following:
1. In the **Resources** navigation pane, choose the **Test** tab. You might need to choose the right arrow button to show the tab.
1. For **function**, enter **HelloWorld**.
1. For **stageName**, enter **beta**.
1. Choose **Test**. You do not need to add a body to your `POST` request.
You get the following response.
```
"Hello, World! I'm calling from the beta stage."
```
1. You can repeat the previous steps to test the **Prod** stage. For **stageName**, enter **Prod**.
You get the following response.
```
"Hello, World! I'm calling from the prod stage."
```
# API Gateway stage variables reference for REST APIs in API Gateway
You can use API Gateway stage variables in the following cases.
## Parameter mapping expressions
A stage variable can be used in a parameter mapping expression for an API method's request or response header parameter, without any partial substitution. In the following example, the stage variable is referenced without the `$` and the enclosing `{...}`.
+ `stageVariables.`
## Mapping templates
A stage variable can be used anywhere in a mapping template, as shown in the following examples.
+ `{ "name" : "$stageVariables."}`
+ `{ "name" : "${stageVariables.}"}`
## HTTP integration URIs
A stage variable can be used as part of an HTTP integration URL, as shown in the following examples:
+ A full URI without protocol – `http://${stageVariables.}`
+ A full domain – `http://${stageVariables.}/resource/operation`
+ A subdomain – `http://${stageVariables.}.example.com/resource/operation`
+ A path – `http://example.com/${stageVariables.}/bar`
+ A query string – `http://example.com/foo?q=${stageVariables.}`
## AWS integration URIs
A stage variable can be used as part of AWS URI action or path components, as shown in the following example.
+ `arn:aws:apigateway:::${stageVariables.}`
## AWS integration URIs (Lambda functions)
A stage variable can be used in place of a Lambda function name, or version/alias, as shown in the following examples.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**Note**
To use a stage variable for a Lambda function, the function must be in the same account as the API. Stage variables don't support cross-account Lambda functions.
## Amazon Cognito user pool
A stage variable can be used in place of a Amazon Cognito user pool for a `COGNITO_USER_POOLS` authorizer.
+ `arn:aws:cognito-idp:::userpool/${stageVariables.}`
## AWS integration credentials
A stage variable can be used as part of AWS user/role credential ARN, as shown in the following example.
+ `arn:aws:iam:::${stageVariables.}`
# Set up an API Gateway canary release deployment
[Canary release](https://martinfowler.com/bliki/CanaryRelease.html) is a software development strategy in which a new version of an API (as well as other software) is deployed for testing purposes, and the base version remains deployed as a production release for normal operations on the same stage. For purposes of discussion, we refer to the base version as a production release in this documentation. Although this is reasonable, you are free to apply canary release on any non-production version for testing.
In a canary release deployment, total API traffic is separated at random into a production release and a canary release with a pre-configured ratio. Typically, the canary release receives a small percentage of API traffic and the production release takes up the rest. The updated API features are only visible to API traffic through the canary. You can adjust the canary traffic percentage to optimize test coverage or performance.
By keeping canary traffic small and the selection random, most users are not adversely affected at any time by potential bugs in the new version, and no single user is adversely affected all the time.
After the test metrics pass your requirements, you can promote the canary release to the production release and disable the canary from the deployment. This makes the new features available in the production stage.
**Topics**
+ [
## Canary release deployment in API Gateway
](#api-gateway-canary-release-deployment-overview)
+ [
# Create a canary release deployment
](create-canary-deployment.md)
+ [
# Update a canary release
](update-canary-deployment.md)
+ [
# Promote a canary release
](promote-canary-deployment.md)
+ [
# Turn off a canary release
](delete-canary-deployment.md)
## Canary release deployment in API Gateway
In API Gateway, a canary release deployment uses the deployment stage for the production release of the base version of an API, and attaches to the stage a canary release for the new versions, relative to the base version, of the API. The stage is associated with the initial deployment and the canary with subsequent deployments. At the beginning, both the stage and the canary point to the same API version. We use stage and production release interchangeably and use canary and canary release interchangeably throughout this section.
To deploy an API with a canary release, you create a canary release deployment by adding [canary settings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) to the [stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) of a regular [deployment](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html). The canary settings describe the underlying canary release and the stage represents the production release of the API within this deployment. To add canary settings, set `canarySettings` on the deployment stage and specify the following:
+ A deployment ID, initially identical to the ID of the base version deployment set on the stage.
+ A [percentage of API traffic](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#percentTraffic), between 0.0 and 100.0 inclusive, for the canary release.
+ [Stage variables for the canary release](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#stageVariableOverrides) that can override production release stage variables.
+ The [use of the stage cache](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache) for canary requests, if the [useStageCache](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#useStageCache) is set and API caching is enabled on the stage.
After a canary release is enabled, the deployment stage cannot be associated with another non-canary release deployment until the canary release is disabled and the canary settings removed from the stage.
When you enable API execution logging, the canary release has its own logs and metrics generated for all canary requests. They are reported to a production stage CloudWatch Logs log group as well as a canary-specific CloudWatch Logs log group. The same applies to access logging. The separate canary-specific logs are helpful to validate new API changes and decide whether to accept the changes and promote the canary release to the production stage, or to discard the changes and revert the canary release from the production stage.
The production stage execution log group is named `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}` and the canary release execution log group is named `API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}/Canary`. For access logging, you must create a new log group or choose an existing one. The canary release access log group name has the `/Canary` suffix appended to the selected log group name.
A canary release can use the stage cache, if enabled, to store responses and use cached entries to return results to the next canary requests, within a pre-configured time-to-live (TTL) period.
In a canary release deployment, the production release and canary release of the API can be associated with the same version or with different versions. When they are associated with different versions, responses for production and canary requests are cached separately and the stage cache returns corresponding results for production and canary requests. When the production release and canary release are associated with the same deployment, the stage cache uses a single cache key for both types of requests and returns the same response for the same requests from the production release and canary release.
# Create a canary release deployment
You create a canary release deployment when deploying the API with [canary settings](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html#canarySettings) as an additional input to the [deployment creation](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDeployment.html) operation.
You can also create a canary release deployment from an existing non-canary deployment by making a [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) request to add the canary settings on the stage.
When creating a non-canary release deployment, you can specify a non-existing stage name. API Gateway creates one if the specified stage does not exist. However, you cannot specify any non-existing stage name when creating a canary release deployment. You will get an error and API Gateway will not create any canary release deployment.
You can create a canary release deployment in API Gateway using the API Gateway console, the AWS CLI, or an AWS SDK.
**Topics**
+ [
## Create a canary deployment using the API Gateway console
](#create-canary-deployment-using-console)
+ [
## Create a canary deployment using the AWS CLI
](#create-canary-deployment-using-cli)
## Create a canary deployment using the API Gateway console
To use the API Gateway console to create a canary release deployment, follow the instructions below:
**To create the initial canary release deployment**
1. Sign in to the API Gateway console.
1. Choose an existing REST API or create a new REST API.
1. In the main navigation pane, choose **Resources**, and then choose **Deploy API**. Follow the on-screen instructions in **Deploy API** to deploy the API to a new stage.
So far, you have deployed the API to a production release stage. Next, you configure canary settings on the stage and, if needed, also enable caching, set stage variables, or configure API execution or access logs.
1. To enable API caching or associate an AWS WAF web ACL with the stage, in the **Stage details** section, choose **Edit**. For more information, see [Cache settings for REST APIs in API Gateway](api-gateway-caching.md) or [To associate an AWS WAF web ACL with an API Gateway API stage using the API Gateway console](apigateway-control-access-aws-waf.md#apigateway-control-access-aws-waf-console).
1. To configure execution or access logging, in the **Logs and tracing** section, choose **Edit** and follow the on-screen instructions. For more information, see [Set up CloudWatch logging for REST APIs in API Gateway](set-up-logging.md).
1. To set stage variables, choose the **Stage variables** tab and follow the on-screen instructions to add or modify stage variables. For more information, see [Use stage variables for a REST API in API Gateway](stage-variables.md).
1. Choose the **Canary** tab, and then choose **Create canary**. You might need to choose the right arrow button to show the **Canary** tab.
1. Under **Canary settings**, for **Canary**, enter the percentage of requests to be diverted to the canary.
1. If desired, select **Stage cache** to turn on caching for the canary release. The cache is not available for the canary release until API caching is enabled.
1. To override existing stage variables, for **Canary override**, enter a new stage variable value.
After the canary release is initialized on the deployment stage, you change the API and want to test the changes. You can redeploy the API to the same stage so that both the updated version and the base version are accessible through the same stage. The following steps describe how to do that.
**To deploy the latest API version to a canary**
1. With each update of the API, choose **Deploy API**.
1. In **Deploy API**, choose the stage that contains a canary from the **Deployment stage** dropdown list.
1. (Optional) Enter a description for **Deployment description**.
1. Choose **Deploy** to push the latest API version to the canary release.
1. If desired, reconfigure the stage settings, logs, or canary settings, as describe in [To create the initial canary release deployment](#to-create-canary-release-on-new-deployment).
As a result, the canary release points to the latest version while the production release still points to the initial version of the API. The [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) now has a new **deploymentId** value, whereas the stage still has the initial [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) value. Behind the scenes, the console calls [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html).
## Create a canary deployment using the AWS CLI
**To create a canary deployment for a new stage**
1. Use the following [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) command to create a deployment with two stage variables, but without a canary:
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'prod'
```
The output will look like the following:
```
{
"id": "du4ot1",
"createdDate": 1511379050
}
```
1. Use the following [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) command to create a canary deployment on the `prod` stage:
```
aws apigateway create-deployment \
--rest-api-id abcd1234 \
--canary-settings percentTraffic=10.5,stageVariableOverrides={sv1='val2',sv2='val3'},useStageCache=false \
--stage-name 'prod'
```
The output will look like the following:
```
{
"id": "a6rox0",
"createdDate": 1511379433
}
```
The resulting deployment `id` identifies the test version of the API for the canary release. As a result, the associated stage is canary-enabled.
1. (Optional) Use the following [get-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-stage.html) command to view the stage representation:
```
aws apigateway get-stage --rest-api-id acbd1234 --stage-name prod
```
The following shows a representation of the `Stage` as the output of the command:
```
{
"stageName": "prod",
"variables": {
"sv0": "val0",
"sv1": "val1"
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "du4ot1",
"lastUpdatedDate": 1511379433,
"createdDate": 1511379050,
"canarySettings": {
"percentTraffic": 10.5,
"deploymentId": "a6rox0",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
}
},
"methodSettings": {}
}
```
In this example, the base version of the API will use the stage variables of `{"sv0":val0", "sv1":val1"}`, while the test version uses the stage variables of `{"sv1":val2", "sv2":val3"}`. Both the production release and canary release use the same stage variable of `sv1`, but with different values, `val1` and `val2`, respectively. The stage variable of `sv0` is used solely in the production release and the stage variable of `sv2` is used in the canary release only.
You can also create a canary release deployment from an existing regular deployment by updating the stage to enable a canary.
**To create a canary release deployment from an existing deployment**
1. Use the [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) command to create a deployment without a canary:
```
aws apigateway create-deployment \
--variables sv0=val0,sv1=val1 \
--rest-api-id abcd1234 \
--stage-name 'beta'
```
1. Use the [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) command to update the stage to enable a canary:
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name 'beta' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
The output will look like the following:
```
{
"stageName": "beta",
"variables": {
"sv0": "val0",
"sv1": "val1"
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "cifeiw",
"lastUpdatedDate": 1511381930,
"createdDate": 1511380879,
"canarySettings": {
"percentTraffic": 10.5,
"deploymentId": "cifeiw",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
}
},
"methodSettings": {}
}
```
Because you enabled a canary on an existing version of the API, both the production release (`Stage`) and canary release (`canarySettings`) point to the same deployment. After you change the API and deploy it to this stage again, the new version will be in the canary release, while the base version remains in the production release. This is manifested in the stage evolution when the `deploymentId` in the canary release is updated to the new deployment `id` and the `deploymentId` in the production release remains unchanged.
# Update a canary release
After a canary release is deployed, you may want to adjust the percentage of the canary traffic or enable or disable the use of a stage cache to optimize the test performance. You can also modify stage variables used in the canary release when the execution context is updated. To make such updates, call the [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) operation with new values on [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings).
You can update a canary release using the API Gateway console, the AWS CLI [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) command or an AWS SDK.
**Topics**
+ [
## Update a canary release using the API Gateway console
](#update-canary-deployment-using-console)
+ [
## Update a canary release using the AWS CLI
](#update-canary-deployment-using-cli)
## Update a canary release using the API Gateway console
To use the API Gateway console to update existing canary settings on a stage, do the following:
**To update existing canary settings**
1. Sign in to the API Gateway console and choose an existing REST API.
1. In the main navigation pane, choose **Stages**, and then choose an existing stage.
1. Choose the **Canary** tab, and then choose **Edit**. You might need to choose the right arrow button to show the **Canary** tab.
1. Update the **Request distribution** by increasing or decreasing the percentage number between 0.0 and 100.0, inclusive.
1. Select or clear the **Stage cache** the check box.
1. Add, remove, or modify **Canary stage variables**.
1. Choose **Save**.
## Update a canary release using the AWS CLI
To use the AWS CLI to update a canary, use the [https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) command and modify the patch operation for each parameter of the canary.
The following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) command updates if the canary uses the stage cache:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations op=replace,path=/canarySettings/useStageCache,value=true
```
The following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) command updates the canary traffic percentage:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations op=replace,path=/canarySettings/percentTraffic,value=25.0
```
The following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) updates stage variables. The example shows how to create a new stage variable named `newVar`, override the `var2` stage variable, and remove the `var1` stage variable:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/newVar",
"value": "newVal"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/var2",
"value": "val4"
}, {
"op": "remove",
"path": "/canarySettings/stageVariableOverrides/var1"
}]'
```
You can update all of the above by combining the operations into a single `patch-operations` value:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"path": "/canarySettings/percentTraffic",
"value": "20.0"
}, {
"op": "replace",
"path": "/canarySettings/useStageCache",
"value": "true"
}, {
"op": "remove",
"path": "/canarySettings/stageVariableOverrides/var1"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/newVar",
"value": "newVal"
}, {
"op": "replace",
"path": "/canarySettings/stageVariableOverrides/val2",
"value": "val4"
}]'
```
# Promote a canary release
When you promote a canary release, the canary release replaces the current stage settings. Promoting a canary release does not disable the canary on the stage. To disable a canary, you must remove the canary settings on the stage. To promote a canary, do the following.
+ Reset the [deployment ID](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#deploymentId) of the stage with the [deployment ID](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) settings of the canary. This updates the API snapshot of the stage with the snapshot of the canary, making the test version the production release as well.
+ Update stage variables with canary stage variables, if any. This updates the API execution context of the stage with that of the canary. Without this update, the new API version may produce unexpected results if the test version uses different stage variables or different values of existing stage variables.
+ Set the percentage of canary traffic to 0.0%.
**Topics**
+ [
## Promote a canary release using the API Gateway console
](#promote-canary-release-deployment-console)
+ [
## Promote a canary release using the AWS CLI
](#promote-canary-release-cli)
## Promote a canary release using the API Gateway console
To use the API Gateway console to promote a canary release deployment, do the following:
**To promote a canary release deployment**
1. Sign in to the API Gateway console and choose an existing API in the primary navigation pane.
1. In the main navigation pane, choose **Stages**, and then choose an existing stage.
1. Choose the **Canary** tab.
1. Choose **Promote canary**.
1. Confirm changes to be made and choose **Promote canary**.
After the promotion, the production release references the same API version (**deploymentId**) as the canary release. You can verify this using the AWS CLI. For example, see [Promote a canary release using the AWS CLI](#promote-canary-release-cli).
## Promote a canary release using the AWS CLI
To promote a canary release to the production release using the AWS CLI commands, call the `update-stage` command to copy the canary-associated `deploymentId` to the stage-associated `deploymentId`, to reset the canary traffic percentage to zero (`0.0`), and, to copy any canary-bound stage variables to the corresponding stage-bound ones.
Suppose we have a canary release deployment, described by a stage similar to the following:
```
{
"_links": {
...
},
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"canarySettings": {
"deploymentId": "eh1sby",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
},
"percentTraffic": 10.5
},
"createdDate": "2017-11-20T04:42:19Z",
"deploymentId": "nfcn0x",
"lastUpdatedDate": "2017-11-22T00:54:28Z",
"methodSettings": {
...
},
"stageName": "prod",
"variables": {
"sv1": "val1"
}
}
```
Use the following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) command to promote the canary:
```
aws apigateway update-stage \
--rest-api-id {rest-api-id} \
--stage-name '{stage-name}' \
--patch-operations '[{
"op": "replace",
"value": "0.0",
"path": "/canarySettings/percentTraffic"
}, {
"op": "copy",
"from": "/canarySettings/stageVariableOverrides",
"path": "/variables"
}, {
"op": "copy",
"from": "/canarySettings/deploymentId",
"path": "/deploymentId"
}]'
```
The output will look like the following:
```
{
"_links": {
...
},
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"canarySettings": {
"deploymentId": "eh1sby",
"useStageCache": false,
"stageVariableOverrides": {
"sv2": "val3",
"sv1": "val2"
},
"percentTraffic": 0
},
"createdDate": "2017-11-20T04:42:19Z",
"deploymentId": "eh1sby",
"lastUpdatedDate": "2017-11-22T05:29:47Z",
"methodSettings": {
...
},
"stageName": "prod",
"variables": {
"sv2": "val3",
"sv1": "val2"
}
}
```
Promoting a canary release to the stage does not disable the canary and the deployment remains to be a canary release deployment. To make it a regular production release deployment, you must disable the canary settings. For more information about how to disable a canary release deployment, see [Turn off a canary release](delete-canary-deployment.md).
# Turn off a canary release
To turn off a canary release deployment is to set the [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) to null to remove it from the stage.
You can disable a canary release deployment using the API Gateway console, the AWS CLI, or an AWS SDK.
**Topics**
+ [
## Turn off a canary release using the API Gateway console
](#delete-canary-release-console)
+ [
## Turn off a canary release using the AWS CLI
](#delete-canary-release-cli)
## Turn off a canary release using the API Gateway console
To use the API Gateway console to turn off a canary release deployment, use the following steps:
**To turn off a canary release deployment**
1. Sign in to the API Gateway console and choose an existing API in the main navigation pane.
1. In the main navigation pane, choose **Stages**, and then choose an existing stage.
1. Choose the **Canary** tab.
1. Choose **Delete**.
1. Confirm you want to delete the canary by choosing **Delete**.
As a result, the [https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) property becomes `null` and is removed from the deployment [stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html). You can verify this using the AWS CLI. For example, see [Turn off a canary release using the AWS CLI](#delete-canary-release-cli).
## Turn off a canary release using the AWS CLI
The following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) command turns off the canary release deployment:
```
aws apigateway update-stage \
--rest-api-id abcd1234 \
--stage-name canary \
--patch-operations '[{"op":"remove", "path":"/canarySettings"}]'
```
The output looks like the following:
```
{
"stageName": "prod",
"accessLogSettings": {
...
},
"cacheClusterEnabled": false,
"cacheClusterStatus": "NOT_AVAILABLE",
"deploymentId": "nfcn0x",
"lastUpdatedDate": 1511309280,
"createdDate": 1511152939,
"methodSettings": {
...
}
}
```
As shown in the output, the [canarySettings](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#canarySettings) property is no longer present in the [stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) of a canary-disabled deployment.
# Updates to REST APIs that require redeployment
Maintaining an API amounts to viewing, updating and deleting the existing API setups. You can maintain an API using the API Gateway console, AWS CLI, CloudFormation, an SDK or the API Gateway REST API. Updating an API involves modifying certain resource properties or configuration settings of the API. Resource updates require redeploying the API, where configuration updates do not.
The following table describes API resources that require redeployment of your API when you update them.
| Resource | Notes |
| --- | --- |
| [ApiKey](https://docs.aws.amazon.com/apigateway/latest/api/API_ApiKey.html) | For applicable properties and supported operations, see [apikey:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateApiKey.html). The update requires redeploying the API. |
| [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | For applicable properties and supported operations, see [authorizer:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAuthorizer.html). The update requires redeploying the API. |
| [disableExecuteApiEndpoint](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html#apigw-UpdateRestApi-response-disableExecuteApiEndpoint) | The update requires modifying any stage on the API such as redeploying the API to a stage. |
| [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) | For applicable properties and supported operations, see [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html). The update requires redeploying the API. |
| [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) | For applicable properties and supported operations, see [documentationversion:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationVersion.html). The update requires redeploying the API. |
| [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) | For applicable properties and supported operations, see [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html#remarks). The update requires redeploying the API. |
| [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) | For applicable properties and supported operations, see [integration:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegration.html). The update requires redeploying the API. |
| [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) | For applicable properties and supported operations, see [integrationresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateIntegrationResponse.html). The update requires redeploying the API. |
| [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | For applicable properties and supported operations, see [method:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethod.html). The update requires redeploying the API. |
| [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) | For applicable properties and supported operations, see [methodresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateMethodResponse.html). The update requires redeploying the API. |
| [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | For applicable properties and supported operations, see [model:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateModel.html). The update requires redeploying the API. |
| [RequestValidator](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) | For applicable properties and supported operations, see [requestvalidator:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRequestValidator.html). The update requires redeploying the API. |
| [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | For applicable properties and supported operations, see [resource:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). The update requires redeploying the API. |
| [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) | For applicable properties and supported operations, see [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html). The update requires redeploying the API. This includes modifying resource policies. |
| [VpcLink](https://docs.aws.amazon.com/apigateway/latest/api/API_VpcLink.html) | For applicable properties and supported operations, see [vpclink:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateVpcLink.html). The update requires redeploying the API. |
The following table describes API configurations that don't require redeployment of your API when you update them.
| Configuration | Notes |
| --- | --- |
| [Account](https://docs.aws.amazon.com/apigateway/latest/api/API_GetAccount.html) | For applicable properties and supported operations, see [account:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html). The update does not require redeploying the API. |
| [Deployment](https://docs.aws.amazon.com/apigateway/latest/api/API_Deployment.html) | For applicable properties and supported operations, see [deployment:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDeployment.html). |
| [DomainName](https://docs.aws.amazon.com/apigateway/latest/api/API_DomainName.html) | For applicable properties and supported operations, see [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html). The update does not require redeploying the API. |
| [BasePathMapping](https://docs.aws.amazon.com/apigateway/latest/api/API_BasePathMapping.html) | For applicable properties and supported operations, see [basepathmapping:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateBasePathMapping.html). The update does not require redeploying the API. |
| [IP address type](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateRestApi.html) | The update does not require redeploying the API. |
| [Stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) | For applicable properties and supported operations, see [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html). The update does not require redeploying the API. |
| [Usage](https://docs.aws.amazon.com/apigateway/latest/api/API_GetUsage.html) | For applicable properties and supported operations, see [usage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsage.html). The update does not require redeploying the API. |
| [UsagePlan](https://docs.aws.amazon.com/apigateway/latest/api/API_UsagePlan.html) | For applicable properties and supported operations, see [usageplan:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateUsagePlan.html). The update does not require redeploying the API. |