@composurecdk/apigateway

API Gateway builders for ComposureCDK.

This package provides a fluent builder for API Gateway REST APIs with secure, AWS-recommended defaults. It wraps the CDK RestApi construct — refer to the CDK documentation for the full set of configurable properties.

REST API Builder

import { createRestApiBuilder } from "@composurecdk/apigateway";

const api = createRestApiBuilder()
  .restApiName("My Service")
  .description("Public API")
  .addResource("users", (users) =>
    users
      .addMethod("GET", listUsersIntegration)
      .addResource("{id}", (user) => user.addMethod("GET", getUserIntegration)),
  )
  .build(stack, "MyApi");

Every RestApiProps property is available as a fluent setter on the builder.

Secure Defaults

createRestApiBuilder applies the following defaults. Each can be overridden via the builder's fluent API.

| Property | Default | Rationale | | ------------------ | ------- | ----------------------------------------------------------------------------------- | | accessLogging | true | Auto-creates a CloudWatch log group for access logging with structured JSON output. | | tracingEnabled | true | Enables X-Ray distributed tracing on the stage. | | loggingLevel | INFO | Enables CloudWatch execution logging for all methods. | | dataTraceEnabled | false | Prevents sensitive request/response bodies from appearing in logs. |

These defaults are guided by the AWS Well-Architected Serverless Applications Lens.

The defaults are exported as REST_API_DEFAULTS for visibility and testing:

import { REST_API_DEFAULTS } from "@composurecdk/apigateway";

Overriding defaults

import { MethodLoggingLevel } from "aws-cdk-lib/aws-apigateway";

const api = createRestApiBuilder()
  .restApiName("My Service")
  .accessLogging(false)
  .deployOptions({ tracingEnabled: false, loggingLevel: MethodLoggingLevel.ERROR })
  .build(stack, "MyApi");

Access logging

By default, the builder creates a CloudWatch log group (using @composurecdk/logs with its secure defaults) and configures it as the stage's access log destination. The created log group is returned in the build result:

const result = createRestApiBuilder()
  .restApiName("My Service")
  .addMethod("GET", integration, methodResponse)
  .build(stack, "MyApi");

result.api; // RestApi
result.accessLogGroup; // LogGroup | undefined

To provide your own destination instead, set deployOptions.accessLogDestination — the auto-created log group is skipped. To disable access logging entirely, set .accessLogging(false).

Recommended Alarms

Both builders create AWS-recommended CloudWatch alarms by default. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.

| Alarm | Metric | Default threshold | Created when | | ------------- | ------------------------- | ----------------- | ------------ | | clientError | 4XXError (Average, 1 min) | > 0.05 (5%) | Always | | serverError | 5XXError (Average, 1 min) | > 0.05 (5%) | Always | | latency | Latency (p90, 1 min) | >= 2500ms | Always |

Alarm metrics include both ApiName and Stage dimensions, targeting the deployment stage created by the builder.

The defaults are exported as REST_API_ALARM_DEFAULTS for visibility and testing:

import { REST_API_ALARM_DEFAULTS } from "@composurecdk/apigateway";

Customizing thresholds

Override individual alarm properties via recommendedAlarms. Unspecified fields keep their defaults.

const api = createRestApiBuilder()
  .restApiName("My Service")
  .addMethod("GET", integration, methodResponse)
  .recommendedAlarms({
    serverError: { threshold: 0.1 }, // 10% error rate
    latency: { threshold: 1000 }, // 1 second p90
    clientError: { evaluationPeriods: 3 }, // fewer evaluation periods
  });

Disabling alarms

Disable all recommended alarms:

builder.recommendedAlarms(false);
// or
builder.recommendedAlarms({ enabled: false });

Disable individual alarms:

builder.recommendedAlarms({ clientError: false, latency: false });

Custom alarms

Add custom alarms alongside the recommended ones via addAlarm. The callback receives an AlarmDefinitionBuilder typed to RestApiBase, so the metric factory has access to the API's properties.

import { Metric } from "aws-cdk-lib/aws-cloudwatch";

const api = createRestApiBuilder()
  .restApiName("My Service")
  .addMethod("GET", integration, methodResponse)
  .addAlarm("integrationLatency", (alarm) =>
    alarm
      .metric(
        (api) =>
          new Metric({
            namespace: "AWS/ApiGateway",
            metricName: "IntegrationLatency",
            dimensionsMap: {
              ApiName: api.restApiName,
              Stage: api.deploymentStage.stageName,
            },
            statistic: "p90",
            period: Duration.minutes(1),
          }),
      )
      .threshold(2000)
      .greaterThanOrEqual()
      .description("Integration latency is elevated"),
  );

Applying alarm actions

Alarms are returned in the build result as Record<string, Alarm>:

const result = api.build(stack, "MyApi");

const alertTopic = new Topic(stack, "AlertTopic");
for (const alarm of Object.values(result.alarms)) {
  alarm.addAlarmAction(new SnsAction(alertTopic));
}

Examples

• MockApiStack — CRUD REST API with mock integrations and recommended alarms with custom thresholds
• MultiStackApp — REST API + Lambda split across stacks via .withStacks(), wired with ref