Skip to main content

Defined in: src/constructs/rest-api/rest-api.ts:39

Properties for configuring a RestApi construct.

This interface extends selected properties from AWS CDK's RestApiProps while adding custom properties for stage management and environment-specific CORS configuration. The construct automatically configures CloudWatch logging, tracing, and metrics based on the provided properties.

Example​

// Production API with strict CORS
const prodApi = new RestApi(this, 'ProdApi', {
  stageName: 'prod',
  description: 'Production API for user management',
  deploy: true,
  isStagingEnvironment: false,
  defaultCorsPreflightOptions: {
    allowOrigins: ['https://myapp.com'],
    allowMethods: ['GET', 'POST'],
    allowHeaders: ['Content-Type', 'Authorization'],
  },
});

// Staging API with permissive CORS
const stagingApi = new RestApi(this, 'StagingApi', {
  stageName: 'staging',
  description: 'Staging API for testing',
  deploy: true,
  isStagingEnvironment: true, // Enables default permissive CORS
});

Extends​

  • Omit<apigw.RestApiProps, "description" | "deploy">

Properties​

apiKeySourceType?​

readonly optional apiKeySourceType: ApiKeySourceType

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:236

The source of the API key for metering requests according to a usage plan.

Default​

- Metering is disabled.

Inherited from​

Omit.apiKeySourceType

binaryMediaTypes?​

readonly optional binaryMediaTypes: string[]

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:200

The list of binary media mime-types that are supported by the RestApi resource, such as "image/png" or "application/octet-stream"

Default​

- RestApi supports only UTF-8-encoded text payloads.

Inherited from​

Omit.binaryMediaTypes

cloneFrom?​

readonly optional cloneFrom: IRestApi

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:229

The ID of the API Gateway RestApi resource that you want to clone.

Default​

- None.

Inherited from​

Omit.cloneFrom

cloudWatchRole?​

readonly optional cloudWatchRole: boolean

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:145

Automatically configure an AWS CloudWatch role for API Gateway.

Default​

  • false if @aws-cdk/aws-apigateway:disableCloudWatchRole is enabled, true otherwise

Inherited from​

Omit.cloudWatchRole

cloudWatchRoleRemovalPolicy?​

readonly optional cloudWatchRoleRemovalPolicy: RemovalPolicy

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:153

The removal policy applied to the AWS CloudWatch role when this resource is removed from the application. Requires cloudWatchRole to be enabled.

Default​

- RemovalPolicy.RETAIN

Inherited from​

Omit.cloudWatchRoleRemovalPolicy

defaultCorsPreflightOptions?​

readonly optional defaultCorsPreflightOptions: CorsOptions

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/resource.d.ts:123

Adds a CORS preflight OPTIONS method to this resource and all child resources.

You can add CORS at the resource-level using addCorsPreflight.

Default​

- CORS is disabled

Inherited from​

Omit.defaultCorsPreflightOptions

defaultIntegration?​

readonly optional defaultIntegration: Integration

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/resource.d.ts:107

An integration to use as a default for all methods created within this API unless an integration is specified.

Default​

- Inherited from parent.

Inherited from​

Omit.defaultIntegration

defaultMethodOptions?​

readonly optional defaultMethodOptions: MethodOptions

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/resource.d.ts:114

Method options to use as a default for all methods created within this API unless custom options are specified.

Default​

- Inherited from parent.

Inherited from​

Omit.defaultMethodOptions

deploy​

deploy: boolean

Defined in: src/constructs/rest-api/rest-api.ts:71

Whether to deploy the API immediately upon creation.

When true, the API will be deployed to the specified stage with all configured logging, tracing, and metrics enabled. When false, you'll need to manually deploy the API later.

Default Value​

true

deployOptions?​

readonly optional deployOptions: StageOptions

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:97

Options for the API Gateway stage that will always point to the latest deployment when deploy is enabled. If deploy is disabled, this value cannot be set.

Default​

  • Based on defaults of StageOptions.

Inherited from​

Omit.deployOptions

description​

description: string

Defined in: src/constructs/rest-api/rest-api.ts:60

A human-readable description of the API.

This description appears in the AWS Console and helps identify the API's purpose. The construct will use this in the format: ${description} ${stageName}.

Example​

'User Management API', 'Order Processing Service'

disableExecuteApiEndpoint?​

readonly optional disableExecuteApiEndpoint: boolean

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:182

Specifies whether clients can invoke the API using the default execute-api endpoint. To require that clients use a custom domain name to invoke the API, disable the default endpoint.

See​

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html

Default​

false

Inherited from​

Omit.disableExecuteApiEndpoint

domainName?​

readonly optional domainName: DomainNameOptions

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:139

Configure a custom domain name and map it to this API.

Default​

  • no domain name is defined, use addDomainName or directly define a DomainName.

Inherited from​

Omit.domainName

endpointConfiguration?​

readonly optional endpointConfiguration: EndpointConfiguration

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:173

The EndpointConfiguration property type specifies the endpoint types of a REST API

See​

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-restapi-endpointconfiguration.html

Default​

EndpointType.EDGE

Inherited from​

Omit.endpointConfiguration

endpointExportName?​

readonly optional endpointExportName: string

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:159

Export name for the CfnOutput containing the API endpoint

Default​

- when no export name is given, output will be created without export

Inherited from​

Omit.endpointExportName

endpointTypes?​

readonly optional endpointTypes: EndpointType[]

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:166

A list of the endpoint types of the API. Use this property when creating an API.

Default​

EndpointType.EDGE

Inherited from​

Omit.endpointTypes

failOnWarnings?​

readonly optional failOnWarnings: boolean

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:133

Indicates whether to roll back the resource if a warning occurs while API Gateway is creating the RestApi resource.

Default​

false

Inherited from​

Omit.failOnWarnings

isStagingEnvironment?​

optional isStagingEnvironment: boolean

Defined in: src/constructs/rest-api/rest-api.ts:87

Whether this API is being deployed in a staging/development environment.

When true, the construct applies permissive CORS settings by default:

  • Allow all origins (*)
  • Allow credentials
  • Allow common HTTP methods (GET, POST, PUT, DELETE, PATCH, OPTIONS)
  • Allow all headers (*)

This should be false for production environments where explicit CORS configuration should be provided via defaultCorsPreflightOptions.

Default Value​

false

minCompressionSize?​

readonly optional minCompressionSize: Size

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:223

A Size(in bytes, kibibytes, mebibytes etc) that is used to enable compression (with non-negative between 0 and 10485760 (10M) bytes, inclusive) or disable compression (when undefined) on an API. When compression is enabled, compression or decompression is not applied on the payload if the payload size is smaller than this value. Setting it to zero allows compression for any payload size.

Default​

- Compression is disabled.

Inherited from​

Omit.minCompressionSize

minimumCompressionSize?​

readonly optional minimumCompressionSize: number

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:212

A nullable integer that is used to enable compression (with non-negative between 0 and 10485760 (10M) bytes, inclusive) or disable compression (when undefined) on an API. When compression is enabled, compression or decompression is not applied on the payload if the payload size is smaller than this value. Setting it to zero allows compression for any payload size.

Default​

- Compression is disabled.

Deprecated​

  • superseded by minCompressionSize

Inherited from​

Omit.minimumCompressionSize

parameters?​

readonly optional parameters: object

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:118

Custom header parameters for the request.

Index Signature​

[key: string]: string

See​

https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html

Default​

- No parameters.

Inherited from​

Omit.parameters

policy?​

readonly optional policy: PolicyDocument

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:126

A policy document that contains the permissions for this RestApi

Default​

- No policy.

Inherited from​

Omit.policy

restApiName?​

readonly optional restApiName: string

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:111

A name for the API Gateway RestApi resource.

Default​

- ID of the RestApi construct.

Inherited from​

Omit.restApiName

retainDeployments?​

readonly optional retainDeployments: boolean

Defined in: node_modules/.pnpm/aws-cdk-lib@2.232.1_constructs@10.0.5/node_modules/aws-cdk-lib/aws-apigateway/lib/restapi.d.ts:105

Retains old deployment resources when the API changes. This allows manually reverting stages to point to old deployments via the AWS Console.

Default​

false

Inherited from​

Omit.retainDeployments

stageName​

stageName: string

Defined in: src/constructs/rest-api/rest-api.ts:50

The stage name for the API deployment.

This is used to name the API and its associated resources, following the pattern: ${constructId}-api-${stageName}. It helps differentiate between environments like 'dev', 'staging', 'prod', etc.

Example​

'prod', 'staging', 'dev', 'ephemeral-123'