Skip to main content

Defined in: src/rest-api/rest-api.ts:145

A REST API construct that creates and configures an AWS API Gateway with best practices.

This construct simplifies the creation of REST APIs by providing:

  • Regional endpoint configuration for better performance and security
  • Automatic CloudWatch logging with configurable retention
  • Distributed tracing and metrics collection
  • Stage-aware CORS configuration
  • Security-focused defaults (disabled execute-api endpoint)
  • Structured naming conventions for multi-environment deployments

The construct automatically sets up comprehensive observability through CloudWatch logs, AWS X-Ray tracing, and CloudWatch metrics. For staging environments, it can apply permissive CORS settings suitable for development, while production environments require explicit CORS configuration.

Example​

// Basic production API
const api = new RestApi(this, 'UserApi', {
  stageName: 'prod',
  description: 'User Management API',
  deploy: true,
  defaultCorsPreflightOptions: {
    allowOrigins: ['https://myapp.com'],
    allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowHeaders: ['Content-Type', 'Authorization'],
    allowCredentials: true,
  },
});

// Add resources and methods to the API
const users = api.api.root.addResource('users');
users.addMethod('GET', new apigw.LambdaIntegration(getUsersFunction));
users.addMethod('POST', new apigw.LambdaIntegration(createUserFunction));

// Development API with permissive CORS
const devApi = new RestApi(this, 'DevApi', {
  stageName: 'dev',
  description: 'Development API',
  deploy: true,
  isStagingEnvironment: true, // Enables permissive CORS
});

Remarks​

The construct creates the following AWS resources:

  • API Gateway REST API with regional endpoint
  • CloudWatch Log Group for access logging (1-day retention)
  • API Gateway deployment with stage configuration
  • CloudWatch role for API Gateway logging

Security considerations:

  • Execute API endpoint is disabled by default for security
  • CloudWatch role is automatically created for audit logging
  • CORS should be explicitly configured for production environments

Extends​

  • Construct

Constructors​

Constructor​

new RestApi(scope, id, props): RestApi

Defined in: src/rest-api/rest-api.ts:240

Creates a new RestApi construct with comprehensive API Gateway configuration.

The constructor sets up a REST API with the following features:

  • Regional endpoint for improved performance and security
  • CloudWatch logging with 1-day retention for cost optimization
  • AWS X-Ray tracing for request tracking
  • CloudWatch metrics for monitoring
  • Stage-aware CORS configuration
  • Disabled execute-api endpoint for security

Parameters​

scope​

Construct

The parent construct (typically a Stack or Stage)

id​

string

A unique identifier for this construct within the scope

props​

ApiProps

Configuration properties for the REST API

Returns​

RestApi

Example​

// Production API with explicit CORS
const prodApi = new RestApi(this, 'ProductionAPI', {
  stageName: 'prod',
  description: 'Production User Management API',
  deploy: true,
  defaultCorsPreflightOptions: {
    allowOrigins: ['https://myapp.com', 'https://admin.myapp.com'],
    allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowHeaders: ['Content-Type', 'Authorization', 'X-Api-Key'],
    allowCredentials: true,
  },
});

// Development API with auto-CORS
const devApi = new RestApi(this, 'DevelopmentAPI', {
  stageName: 'dev',
  description: 'Development API',
  deploy: true,
  isStagingEnvironment: true,
});

Throws​

Will throw an error if the API Gateway creation fails

Remarks​

The construct automatically creates:

  • A CloudWatch Log Group named ${id}ApiLogs with 1-day retention
  • An API Gateway REST API named ${id}-api-${stageName}
  • A deployment stage named 'api' with logging and tracing enabled
  • A CloudWatch role for API Gateway service logging

Overrides​

Construct.constructor

Properties​

api​

readonly api: RestApi

Defined in: src/rest-api/rest-api.ts:171

The underlying AWS API Gateway REST API instance.

This provides direct access to the API Gateway for adding resources, methods, and integrations. You can use this to:

  • Add resources: api.root.addResource('users')
  • Add methods: resource.addMethod('GET', integration)
  • Configure authorizers, validators, and other API Gateway features

Example​

const restApi = new RestApi(this, 'MyApi', { ... });

// Add a resource
const users = restApi.api.root.addResource('users');

// Add methods with integrations
users.addMethod('GET', new apigw.LambdaIntegration(listUsersFunction));
users.addMethod('POST', new apigw.LambdaIntegration(createUserFunction));

// Add nested resources
const userById = users.addResource('{id}');
userById.addMethod('GET', new apigw.LambdaIntegration(getUserFunction));

node​

readonly node: Node

Defined in: node_modules/.pnpm/constructs@10.4.2/node_modules/constructs/lib/construct.d.ts:266

The tree node.

Inherited from​

Construct.node

Methods​

toString()​

toString(): string

Defined in: node_modules/.pnpm/constructs@10.4.2/node_modules/constructs/lib/construct.d.ts:279

Returns a string representation of this construct.

Returns​

string

Inherited from​

Construct.toString

isConstruct()​

static isConstruct(x): x is Construct

Defined in: node_modules/.pnpm/constructs@10.4.2/node_modules/constructs/lib/construct.d.ts:262

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

Parameters​

x​

any

Any object

Returns​

x is Construct

true if x is an object created from a class which extends Construct.

Inherited from​

Construct.isConstruct