AWS::ApiGateway::Stage

The AWS::ApiGateway::Stage resource creates a stage for a 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,
      "Tags" : [ Tag, ... ],
      "TracingEnabled" : Boolean,
      "Variables" : {Key : Value, ...}
    }
}

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
  Tags: 
    - Tag
  TracingEnabled: Boolean
  Variables: 
    Key : Value

Properties

AccessLogSetting

Specifies settings for logging access in this stage.

Required: No

Type: 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: CanarySetting

Update requires: No interruption

ClientCertificateId

The ID 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 is associated with. This parameter is required to create a stage.

Required: Conditional

Type: String

Update requires: No interruption

Description

A description of the stage.

Required: No

Type: String

Update requires: No interruption

DocumentationVersion

The version ID of the API documentation snapshot.

Required: No

Type: String

Update requires: No interruption

MethodSettings

Settings for all methods in the stage.

Required: No

Type: List of 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: No

Type: String

Update requires: Replacement

Tags

An array of arbitrary tags (key-value pairs) to associate with the stage.

Required: No

Type: List of Tag

Update requires: No interruption

TracingEnabled

Specifies whether active X-Ray tracing is enabled for this stage.

For more information, see Trace API Gateway API Execution with AWS X-Ray in the API Gateway Developer Guide.

Required: No

Type: Boolean

Update requires: No interruption

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: Map of String

Update requires: No interruption

Return values

Ref

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

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

Examples

Create stage

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": "false"
                    },
                    {
                        "ResourcePath": "/stack",
                        "HttpMethod": "POST",
                        "MetricsEnabled": "true",
                        "DataTraceEnabled": "false",
                        "ThrottlingBurstLimit": "999"
                    },
                    {
                        "ResourcePath": "/stack",
                        "HttpMethod": "GET",
                        "MetricsEnabled": "true",
                        "DataTraceEnabled": "false",
                        "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: 'false'
        - ResourcePath: /stack
          HttpMethod: POST
          MetricsEnabled: 'true'
          DataTraceEnabled: 'false'
          ThrottlingBurstLimit: '999'
        - ResourcePath: /stack
          HttpMethod: GET
          MetricsEnabled: 'true'
          DataTraceEnabled: 'false'
          ThrottlingBurstLimit: '555'

See also

• stage:create in the Amazon API Gateway REST API Reference