Aligent AWS Secure REST API

Overview

A CDK construct for provisioning an API Gateway REST API secured with API Key authentication and usage plan throttling. Routes accept any CDK Integration, giving callers full control over how endpoints are wired.

Features

• API Gateway REST API with API Key authentication (apiKeyRequired: true on all routes)
• Usage plan with configurable throttle rate and burst limits
• Configurable CORS preflight options
• Accepts any CDK Integration per route (Lambda, HTTP, Mock, Step Functions, etc.)
• Supports nested, multi-segment route paths (e.g. rewards/accounts/{accountId}/redeem)
• Supports alias paths so a route can be exposed under an additional path (e.g. renaming an endpoint without breaking existing consumers)
• Configurable deployment stage via deployOptions (stage name defaults to prod)

Installation

npm install @aligent/cdk-secure-rest-api

Or with yarn:

yarn add @aligent/cdk-secure-rest-api aws-cdk-lib constructs

Peer Dependencies

• aws-cdk-lib (^2.113.0)
• constructs (^10.5.0)

Basic Usage

import { SecureRestApi } from '@aligent/cdk-secure-rest-api';
import { LambdaIntegration } from 'aws-cdk-lib/aws-apigateway';
import { HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';

const api = new SecureRestApi(this, 'Api', {
  apiName: 'my-api',
  routes: [
    {
      path: 'items',
      methods: [HttpMethod.GET],
      integration: new LambdaIntegration(myFunction),
    },
  ],
});

// Access created resources
const { api, apiKey, usagePlan } = api;

Configuration Examples

Multiple routes and methods

const api = new SecureRestApi(this, 'Api', {
  apiName: 'my-api',
  routes: [
    {
      path: 'items',
      methods: [HttpMethod.GET, HttpMethod.POST],
      integration: new LambdaIntegration(itemsFunction),
    },
    {
      path: 'orders',
      methods: [HttpMethod.GET],
      integration: new LambdaIntegration(ordersFunction),
    },
  ],
});

Nested route paths

Multi-segment paths create the intermediate resources automatically. Routes sharing a common prefix resolve to the same parent resource.

const api = new SecureRestApi(this, 'Api', {
  apiName: 'rewards-api',
  routes: [
    {
      path: 'rewards/accounts/{accountId}/redeem',
      methods: [HttpMethod.POST],
      integration: new LambdaIntegration(redeemFunction),
    },
    {
      path: 'rewards/reversal', // reuses the shared `rewards` resource
      methods: [HttpMethod.POST],
      integration: new LambdaIntegration(reversalFunction),
    },
  ],
});

Alias paths

Expose a route under one or more additional paths, useful when renaming an endpoint without breaking existing consumers: keep the old path as an alias until callers migrate to the new one, then drop aliasPaths once it's safe.

const api = new SecureRestApi(this, 'Api', {
  apiName: 'my-api',
  routes: [
    {
      path: 'customers',
      methods: [HttpMethod.GET],
      integration: new LambdaIntegration(customersFunction),
      aliasPaths: ['people'], // old path, kept working during migration
    },
  ],
});

Alias paths work with nested routes too, as long as the parameter names match:

const api = new SecureRestApi(this, 'Api', {
  apiName: 'my-api',
  routes: [
    {
      path: 'customers/{id}/addresses',
      methods: [HttpMethod.GET],
      integration: new LambdaIntegration(addressesFunction),
      aliasPaths: ['people/{id}/addresses'],
    },
  ],
});

Custom throttling

const api = new SecureRestApi(this, 'Api', {
  apiName: 'my-api',
  throttle: {
    rateLimit: 50,   // requests per second
    burstLimit: 100,
  },
  routes: [...],
});

Custom stage name

By default the API deploys to a prod stage. Pass deployOptions to override the stage name (or any other CDK StageOptions, e.g. logging or tracing).

const api = new SecureRestApi(this, 'Api', {
  apiName: 'my-api',
  deployOptions: { stageName: 'staging' },
  routes: [...],
});

Custom CORS configuration

const api = new SecureRestApi(this, 'Api', {
  apiName: 'my-api',
  corsOptions: {
    allowOrigins: ['https://example.com'],  // overrides default (all origins)
    additionalMethods: ['POST'],            // appended to GET, OPTIONS
    additionalHeaders: ['Authorization'],   // appended to Content-Type, X-Api-Key
  },
  routes: [...],
});

Configuration Reference

apiName (string) — required

The name of the REST API and the base for generated resource names.

description (string)

Description for the API Gateway REST API.

Default: REST API for {apiName} service

routes (SecureRestApiRoute[]) — required

Routes to register on the API. Each route requires:

| Property | Type | Description | |----------|------|-------------| | path | string | The resource path; may be nested/multi-segment (leading slash is stripped automatically) | | methods | HttpMethod[] | HTTP methods to register on the resource | | integration | Integration | Any CDK API Gateway integration | | aliasPaths | string[] | Optional. Additional paths that register the same methods and integration |

deployOptions (StageOptions)

Stage options for the API's default deployment, passed through to the underlying CDK RestApi. Use stageName to override the deployed stage name.

Default: CDK default (prod stage).

throttle (object)

Throttling limits applied to the usage plan.

| Property | Type | Default | |----------|------|---------| | rateLimit | number | 100 | | burstLimit | number | 200 |

corsOptions (object)

CORS preflight configuration applied to all resources.

| Property | Type | Behaviour | |----------|------|-----------| | allowOrigins | string[] | Overrides the default (all origins) | | additionalMethods | string[] | Appended to the defaults: GET, OPTIONS | | additionalHeaders | string[] | Appended to the defaults: Content-Type, X-Api-Key |

apiKeyName (string)

Override the name of the generated API key.

Default: {apiName}-api-key

usagePlanName (string)

Override the name of the generated usage plan.

Default: {apiName}-usage-plan

Local Development

NPM link can be used to develop the module locally:

1. Pull this repository locally
2. cd into this repository
3. Run npm link
4. cd into the downstream repo and run npm link '@aligent/cdk-secure-rest-api'

The downstream repository should now include a symlink to this module, allowing local changes to be tested before pushing.