secure-rest-api

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)
• 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),
    },
  ],
});

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

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.