AWS::ApiGateway::Stage - AWS CloudFormation

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