StageProps

class aws_cdk.aws_apigateway.StageProps(*, cache_data_encrypted=None, cache_ttl=None, caching_enabled=None, data_trace_enabled=None, logging_level=None, metrics_enabled=None, throttling_burst_limit=None, throttling_rate_limit=None, access_log_destination=None, access_log_format=None, cache_cluster_enabled=None, cache_cluster_size=None, client_certificate_id=None, description=None, documentation_version=None, method_options=None, stage_name=None, tracing_enabled=None, variables=None, deployment)

Bases: StageOptions

Parameters:
  • cache_data_encrypted (Optional[bool]) – Indicates whether the cached responses are encrypted. Default: false

  • cache_ttl (Optional[Duration]) – Specifies the time to live (TTL), in seconds, for cached responses. The higher the TTL, the longer the response will be cached. Default: Duration.minutes(5)

  • caching_enabled (Optional[bool]) – Specifies whether responses should be cached and returned for requests. A cache cluster must be enabled on the stage for responses to be cached. Default: - Caching is Disabled.

  • data_trace_enabled (Optional[bool]) – Specifies whether data trace logging is enabled for this method. When enabled, API gateway will log the full API requests and responses. This can be useful to troubleshoot APIs, but can result in logging sensitive data. We recommend that you don’t enable this feature for production APIs. Default: false

  • logging_level (Optional[MethodLoggingLevel]) – Specifies the logging level for this method, which effects the log entries pushed to Amazon CloudWatch Logs. Default: - Off

  • metrics_enabled (Optional[bool]) – Specifies whether Amazon CloudWatch metrics are enabled for this method. Default: false

  • throttling_burst_limit (Union[int, float, None]) – Specifies the throttling burst limit. The total rate of all requests in your AWS account is limited to 5,000 requests. Default: - No additional restriction.

  • throttling_rate_limit (Union[int, float, None]) – Specifies the throttling rate limit. The total rate of all requests in your AWS account is limited to 10,000 requests per second (rps). Default: - No additional restriction.

  • access_log_destination (Optional[IAccessLogDestination]) – The CloudWatch Logs log group or Firehose delivery stream where to write access logs. Default: - No destination

  • access_log_format (Optional[AccessLogFormat]) – A single line format of access logs of data, as specified by selected $content variables. The format must include either AccessLogFormat.contextRequestId() or AccessLogFormat.contextExtendedRequestId(). Default: - Common Log Format

  • cache_cluster_enabled (Optional[bool]) – Indicates whether cache clustering is enabled for the stage. Default: - Disabled for the stage.

  • cache_cluster_size (Optional[str]) – The stage’s cache cluster size. Default: 0.5

  • client_certificate_id (Optional[str]) – The identifier of the client certificate that API Gateway uses to call your integration endpoints in the stage. Default: - None.

  • description (Optional[str]) – A description of the purpose of the stage. Default: - No description.

  • documentation_version (Optional[str]) – The version identifier of the API documentation snapshot. Default: - No documentation version.

  • method_options (Optional[Mapping[str, Union[MethodDeploymentOptions, Dict[str, Any]]]]) – Method deployment options for specific resources/methods. These will override common options defined in StageOptions#methodOptions. Default: - Common options will be used.

  • stage_name (Optional[str]) – The name of the stage, which API Gateway uses as the first path segment in the invoked Uniform Resource Identifier (URI). Default: - “prod”

  • tracing_enabled (Optional[bool]) – Specifies whether Amazon X-Ray tracing is enabled for this method. Default: false

  • variables (Optional[Mapping[str, str]]) – A map that defines the stage variables. Variable names must consist of alphanumeric characters, and the values must match the following regular expression: [A-Za-z0-9-._~:/?#&=,]+. Default: - No stage variables.

  • deployment (Deployment) – The deployment that this stage points to [disable-awslint:ref-via-interface].

ExampleMetadata:

infused

Example:

# production stage
prod_log_group = logs.LogGroup(self, "PrdLogs")
api = apigateway.RestApi(self, "books",
    deploy_options=apigateway.StageOptions(
        access_log_destination=apigateway.LogGroupLogDestination(prod_log_group),
        access_log_format=apigateway.AccessLogFormat.json_with_standard_fields()
    )
)
deployment = apigateway.Deployment(self, "Deployment", api=api)

# development stage
dev_log_group = logs.LogGroup(self, "DevLogs")
apigateway.Stage(self, "dev",
    deployment=deployment,
    access_log_destination=apigateway.LogGroupLogDestination(dev_log_group),
    access_log_format=apigateway.AccessLogFormat.json_with_standard_fields(
        caller=False,
        http_method=True,
        ip=True,
        protocol=True,
        request_time=True,
        resource_path=True,
        response_length=True,
        status=True,
        user=True
    )
)

Attributes

access_log_destination

The CloudWatch Logs log group or Firehose delivery stream where to write access logs.

Default:
  • No destination

access_log_format

A single line format of access logs of data, as specified by selected $content variables.

The format must include either AccessLogFormat.contextRequestId() or AccessLogFormat.contextExtendedRequestId().

Default:
  • Common Log Format

See:

https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#context-variable-reference

cache_cluster_enabled

Indicates whether cache clustering is enabled for the stage.

Default:
  • Disabled for the stage.

cache_cluster_size

The stage’s cache cluster size.

Default:

0.5

cache_data_encrypted

Indicates whether the cached responses are encrypted.

Default:

false

cache_ttl

Specifies the time to live (TTL), in seconds, for cached responses.

The higher the TTL, the longer the response will be cached.

Default:

Duration.minutes(5)

See:

https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html

caching_enabled

Specifies whether responses should be cached and returned for requests.

A cache cluster must be enabled on the stage for responses to be cached.

Default:
  • Caching is Disabled.

client_certificate_id

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

Default:
  • None.

data_trace_enabled

Specifies whether data trace logging is enabled for this method.

When enabled, API gateway will log the full API requests and responses. This can be useful to troubleshoot APIs, but can result in logging sensitive data. We recommend that you don’t enable this feature for production APIs.

Default:

false

deployment

ref-via-interface].

Type:

The deployment that this stage points to [disable-awslint

description

A description of the purpose of the stage.

Default:
  • No description.

documentation_version

The version identifier of the API documentation snapshot.

Default:
  • No documentation version.

logging_level

Specifies the logging level for this method, which effects the log entries pushed to Amazon CloudWatch Logs.

Default:
  • Off

method_options

Method deployment options for specific resources/methods.

These will override common options defined in StageOptions#methodOptions.

Default:
  • Common options will be used.

metrics_enabled

Specifies whether Amazon CloudWatch metrics are enabled for this method.

Default:

false

stage_name

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

Default:
  • “prod”

throttling_burst_limit

Specifies the throttling burst limit.

The total rate of all requests in your AWS account is limited to 5,000 requests.

Default:
  • No additional restriction.

See:

https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html

throttling_rate_limit

Specifies the throttling rate limit.

The total rate of all requests in your AWS account is limited to 10,000 requests per second (rps).

Default:
  • No additional restriction.

See:

https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html

tracing_enabled

Specifies whether Amazon X-Ray tracing is enabled for this method.

Default:

false

variables

A map that defines the stage variables.

Variable names must consist of alphanumeric characters, and the values must match the following regular expression: [A-Za-z0-9-._~:/?#&=,]+.

Default:
  • No stage variables.