# StageProps

Extends: [StageOptions](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.StageOptions.html)
Used as props by: [Stage](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.Stage.html)

- Source: [`aws-apigateway/lib/stage.ts`](https://github.com/aws/aws-cdk/blob/v2.278.0/packages/aws-cdk-lib/aws-apigateway/lib/stage.ts#L133)

## Example

TypeScript:

```ts
// production stage
const prodLogGroup = new logs.LogGroup(this, "PrdLogs");
const api = new apigateway.RestApi(this, 'books', {
  deployOptions: {
    accessLogDestination: new apigateway.LogGroupLogDestination(prodLogGroup),
    accessLogFormat: apigateway.AccessLogFormat.jsonWithStandardFields(),
  },
});
const deployment = new apigateway.Deployment(this, 'Deployment', {api});

// development stage
const devLogGroup = new logs.LogGroup(this, "DevLogs");
new apigateway.Stage(this, 'dev', {
  deployment,
  accessLogDestination: new apigateway.LogGroupLogDestination(devLogGroup),
  accessLogFormat: apigateway.AccessLogFormat.jsonWithStandardFields({
    caller: false,
    httpMethod: true,
    ip: true,
    protocol: true,
    requestTime: true,
    resourcePath: true,
    responseLength: true,
    status: true,
    user: true,
  }),
});
```

Python:

```python
# 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
    )
)
```

Java:

```java
// production stage
LogGroup prodLogGroup = new LogGroup(this, "PrdLogs");
RestApi api = RestApi.Builder.create(this, "books")
        .deployOptions(StageOptions.builder()
                .accessLogDestination(new LogGroupLogDestination(prodLogGroup))
                .accessLogFormat(AccessLogFormat.jsonWithStandardFields())
                .build())
        .build();
Deployment deployment = Deployment.Builder.create(this, "Deployment").api(api).build();

// development stage
LogGroup devLogGroup = new LogGroup(this, "DevLogs");
Stage.Builder.create(this, "dev")
        .deployment(deployment)
        .accessLogDestination(new LogGroupLogDestination(devLogGroup))
        .accessLogFormat(AccessLogFormat.jsonWithStandardFields(JsonWithStandardFieldProps.builder()
                .caller(false)
                .httpMethod(true)
                .ip(true)
                .protocol(true)
                .requestTime(true)
                .resourcePath(true)
                .responseLength(true)
                .status(true)
                .user(true)
                .build()))
        .build();
```

C# / .NET:

```csharp
// Install: dotnet add package Amazon.CDK.Lib
// production stage
var prodLogGroup = new LogGroup(this, "PrdLogs");
var api = new RestApi(this, "books", new RestApiProps {
    DeployOptions = new StageOptions {
        AccessLogDestination = new LogGroupLogDestination(prodLogGroup),
        AccessLogFormat = AccessLogFormat.JsonWithStandardFields()
    }
});
var deployment = new Deployment(this, "Deployment", new DeploymentProps { Api = api });

// development stage
var devLogGroup = new LogGroup(this, "DevLogs");
new Stage(this, "dev", new StageProps {
    Deployment = deployment,
    AccessLogDestination = new LogGroupLogDestination(devLogGroup),
    AccessLogFormat = AccessLogFormat.JsonWithStandardFields(new JsonWithStandardFieldProps {
        Caller = false,
        HttpMethod = true,
        Ip = true,
        Protocol = true,
        RequestTime = true,
        ResourcePath = true,
        ResponseLength = true,
        Status = true,
        User = true
    })
});
```

Golang:

```go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
// production stage
prodLogGroup := logs.NewLogGroup(this, jsii.String("PrdLogs"))
api := apigateway.NewRestApi(this, jsii.String("books"), &RestApiProps{
	DeployOptions: &StageOptions{
		AccessLogDestination: apigateway.NewLogGroupLogDestination(prodLogGroup),
		AccessLogFormat: apigateway.AccessLogFormat_JsonWithStandardFields(),
	},
})
deployment := apigateway.NewDeployment(this, jsii.String("Deployment"), &DeploymentProps{
	Api: Api,
})

// development stage
devLogGroup := logs.NewLogGroup(this, jsii.String("DevLogs"))
apigateway.NewStage(this, jsii.String("dev"), &StageProps{
	Deployment: Deployment,
	AccessLogDestination: apigateway.NewLogGroupLogDestination(devLogGroup),
	AccessLogFormat: apigateway.AccessLogFormat_*JsonWithStandardFields(&JsonWithStandardFieldProps{
		Caller: jsii.Boolean(false),
		HttpMethod: jsii.Boolean(true),
		Ip: jsii.Boolean(true),
		Protocol: jsii.Boolean(true),
		RequestTime: jsii.Boolean(true),
		ResourcePath: jsii.Boolean(true),
		ResponseLength: jsii.Boolean(true),
		Status: jsii.Boolean(true),
		User: jsii.Boolean(true),
	}),
})
```

## Properties

- `accessLogDestination`: [IAccessLogDestination](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.IAccessLogDestination.html) — The CloudWatch Logs log group or Firehose delivery stream where to write access logs.

  **Default:** No destination

- `accessLogFormat`: [AccessLogFormat](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.AccessLogFormat.html) — A single line format of access logs of data, as specified by selected $content variables.

  **Default:** Common Log Format

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

- `cacheClusterEnabled`: boolean — Indicates whether cache clustering is enabled for the stage.

  **Default:** Disabled for the stage.

- `cacheClusterSize`: string = 0.5 — The stage's cache cluster size.

- `cacheDataEncrypted`: boolean = false — Indicates whether the cached responses are encrypted.

- `cacheTtl`: [Duration](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = Duration.minutes(5) — Specifies the time to live (TTL), in seconds, for cached responses.

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

- `cachingEnabled`: boolean — Specifies whether responses should be cached and returned for requests.

  **Default:** Caching is Disabled.

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

- `clientCertificateId`: string = None. — The identifier of the client certificate that API Gateway uses to call your integration endpoints in the stage.

- `dataTraceEnabled`: boolean = false — 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.

- `deployment`: [Deployment](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.Deployment.html) (required) — The deployment that this stage points to [disable-awslint:ref-via-interface].

- `description`: string — A description of the purpose of the stage.

  **Default:** No description.

- `documentationVersion`: string — The version identifier of the API documentation snapshot.

  **Default:** No documentation version.

- `loggingLevel`: [MethodLoggingLevel](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.MethodLoggingLevel.html) = Off — Specifies the logging level for this method, which effects the log entries pushed to Amazon CloudWatch Logs.

- `methodOptions`: { [key: string]: [MethodDeploymentOptions](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.MethodDeploymentOptions.html) } — Method deployment options for specific resources/methods.

  **Default:** Common options will be used.

  These will
  override common options defined in `StageOptions#methodOptions`.

- `metricsEnabled`: boolean = false — Specifies whether Amazon CloudWatch metrics are enabled for this method.

- `stageName`: string = "prod" — The name of the stage, which API Gateway uses as the first path segment in the invoked Uniform Resource Identifier (URI).

- `throttlingBurstLimit`: number — Specifies the throttling burst limit.

  **Default:** No additional restriction.

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

- `throttlingRateLimit`: number — Specifies the throttling rate limit.

  **Default:** No additional restriction.

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

- `tracingEnabled`: boolean = false — Specifies whether Amazon X-Ray tracing is enabled for this method.

- `variables`: { [key: string]: string } — A map that defines the stage variables.

  **Default:** No stage variables.

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