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.)

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

Custom throttling

const api = new SecureRestApi(this, 'Api', {
  apiName: 'my-api',
  throttle: {
    rateLimit: 50,   // requests per second
    burstLimit: 100,
  },
  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 (leading slash is stripped automatically)
methods	HttpMethod[]	HTTP methods to register on the resource
integration	Integration	Any CDK API Gateway integration

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.