AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS::ApiGateway::Stage

The AWS::ApiGateway::Stage resource creates a stage for an Amazon API Gateway (API Gateway) deployment.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{ "Type" : "AWS::ApiGateway::Stage", "Properties" : { "AccessLogSetting" : AccessLogSetting, "CacheClusterEnabled" : Boolean, "CacheClusterSize" : String, "CanarySetting" : CanarySetting, "ClientCertificateId" : String, "DeploymentId" : String, "Description" : String, "DocumentationVersion" : String, "MethodSettings" : [ MethodSetting, ... ], "RestApiId" : String, "StageName" : String, "Variables" : { String:String, ... } } }

YAML

Type: AWS::ApiGateway::Stage Properties: AccessLogSetting: AccessLogSetting CacheClusterEnabled: Boolean CacheClusterSize: String CanarySetting: CanarySetting ClientCertificateId: String DeploymentId: String Description: String DocumentationVersion: String MethodSettings: - MethodSetting RestApiId: String StageName: String Variables: String: String

Properties

AccessLogSetting

Specifies settings for logging access in this stage.

Required: No

Type: API Gateway Stage AccessLogSetting

Update requires: No interruption

CacheClusterEnabled

Indicates whether cache clustering is enabled for the stage.

Required: No

Type: Boolean

Update requires: No interruption

CacheClusterSize

The stage's cache cluster size.

Required: No

Type: String

Update requires: No interruption

CanarySetting

Specifies settings for the canary deployment in this stage.

Required: No

Type: API Gateway Stage CanarySetting

Update requires: No interruption

ClientCertificateId

The identifier of the client certificate that API Gateway uses to call your integration endpoints in the stage.

Required: No

Type: String

Update requires: No interruption

DeploymentId

The ID of the deployment that the stage points to.

Required: Yes

Type: String

Update requires: No interruption

Description

A description of the stage's purpose.

Required: No

Type: String

Update requires: No interruption

DocumentationVersion

The version identifier of the API documentation snapshot.

Required: No

Type: String

MethodSettings

Settings for all methods in the stage.

Required: No

Type: List of API Gateway Stage MethodSetting

Update requires: No interruption

RestApiId

The ID of the RestApi resource that you're deploying with this stage.

Required: Yes

Type: String

Update requires: Replacement

StageName

The name of the stage, which API Gateway uses as the first path segment in the invoked Uniform Resource Identifier (URI).

Required: Yes

Type: String

Update requires: Replacement

Variables

A map (string-to-string map) that defines the stage variables, where the variable name is the key and the variable value is the value. Variable names are limited to alphanumeric characters. Values must match the following regular expression: [A-Za-z0-9-._~:/?#&=,]+.

Required: No

Type: Mapping of key-value pairs

Update requires: No interruption

Return Value

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the name of the stage, such as MyTestStage.

For more information about using the Ref function, see Ref.

Example

The following example creates a stage for the TestDeployment deployment. The stage also specifies method settings for the MyRestApi API.

JSON

{ "Resources": { "Prod": { "Type": "AWS::ApiGateway::Stage", "Properties": { "StageName": "Prod", "Description": "Prod Stage", "RestApiId": { "Ref": "MyRestApi" }, "DeploymentId": { "Ref": "TestDeployment" }, "DocumentationVersion": { "Ref": "MyDocumentationVersion" }, "ClientCertificateId": { "Ref": "ClientCertificate" }, "Variables": { "Stack": "Prod" }, "MethodSettings": [ { "ResourcePath": "/", "HttpMethod": "GET", "MetricsEnabled": "true", "DataTraceEnabled": "true" }, { "ResourcePath": "/stack", "HttpMethod": "POST", "MetricsEnabled": "true", "DataTraceEnabled": "true", "ThrottlingBurstLimit": "999" }, { "ResourcePath": "/stack", "HttpMethod": "GET", "MetricsEnabled": "true", "DataTraceEnabled": "true", "ThrottlingBurstLimit": "555" } ] } } } }

YAML

Resources: Prod: Type: AWS::ApiGateway::Stage Properties: StageName: Prod Description: Prod Stage RestApiId: !Ref MyRestApi DeploymentId: !Ref TestDeployment DocumentationVersion: !Ref MyDocumentationVersion ClientCertificateId: !Ref ClientCertificate Variables: Stack: Prod MethodSettings: - ResourcePath: / HttpMethod: GET MetricsEnabled: 'true' DataTraceEnabled: 'true' - ResourcePath: /stack HttpMethod: POST MetricsEnabled: 'true' DataTraceEnabled: 'true' ThrottlingBurstLimit: '999' - ResourcePath: /stack HttpMethod: GET MetricsEnabled: 'true' DataTraceEnabled: 'true' ThrottlingBurstLimit: '555'