AWS::ApiGateway::Stage - AWS CloudFormation
SyntaxPropertiesReturn valuesExamplesSee also

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

Access log settings, including the access log format and access log destination ARN.

Required: No

Type: AccessLogSetting

Update requires: No interruption

CacheClusterEnabled

Specifies whether a cache cluster is enabled for the stage. To activate a method-level cache, set CachingEnabled to true for a method.

Required: No

Type: Boolean

Update requires: No interruption

CacheClusterSize

The stage's cache capacity in GB. For more information about choosing a cache size, see Enabling API caching to enhance responsiveness.

Required: No

Type: String

Allowed values: 0.5 | 1.6 | 6.1 | 13.5 | 28.4 | 58.2 | 118 | 237

Update requires: No interruption

CanarySetting

Settings for the canary deployment in this stage.

Required: No

Type: CanarySetting

Update requires: No interruption

ClientCertificateId

The identifier of a client certificate for an API stage.

Required: No

Type: String

Update requires: No interruption

DeploymentId

The identifier of the Deployment that the stage points to.

Required: No

Type: String

Update requires: No interruption

Description

The stage's description.

Required: No

Type: String

Update requires: No interruption

DocumentationVersion

The version of the associated API documentation.

Required: No

Type: String

Update requires: No interruption

MethodSettings

A map that defines the method settings for a Stage resource. Keys (designated as /{method_setting_key below) are method paths defined as {resource_path}/{http_method} for an individual method override, or /\*/\* for overriding all methods in the stage.

Required: No

Type: Array of MethodSetting

Update requires: No interruption

RestApiId

The string identifier of the associated RestApi.

Required: Yes

Type: String

Update requires: Replacement

StageName

The name of the stage is the first path segment in the Uniform Resource Identifier (URI) of a call to API Gateway. Stage names can only contain alphanumeric characters, hyphens, and underscores. Maximum length is 128 characters.

Required: No

Type: String

Update requires: Replacement

Tags

The collection of tags. Each tag element is associated with a given resource.

Required: No

Type: Array of Tag

Update requires: No interruption

TracingEnabled

Specifies whether active tracing with X-ray is enabled for the Stage.

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

Pattern: [a-zA-Z0-9]+

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