AWS API Gateway Tools

Tools and a get-dotenv plugin for working with AWS API Gateway (REST APIs), including stage cache flush and API key retrieval.

This package provides:

• A tools-style wrapper that owns AWS client setup (including optional AWS X-Ray capture):
  • AwsApiGatewayTools
• A get-dotenv plugin intended to be mounted under aws:
  • apiGatewayPlugin() → aws api-gateway flush-cache|pull-keys
• A CLI embedding get-dotenv with the api-gateway plugin:
  • aws-api-gateway-tools

Documentation

• Learn the programmatic API: AwsApiGatewayTools guide
• Learn the CLI and plugin behavior: aws api-gateway plugin guide
• Browse the generated API reference: TypeDoc site

Install

npm i @karmaniverous/aws-api-gateway-tools
Copy

This package is ESM-only (Node >= 20).

Quick start (programmatic)

import { AwsApiGatewayTools } from '@karmaniverous/aws-api-gateway-tools';

const tools = new AwsApiGatewayTools({
  clientConfig: { region: 'us-east-1', logger: console },
  xray: 'auto',
});

await tools.flushStageCache({ restApiId: 'abc123', stageName: 'dev' });
Copy

When you need AWS functionality not wrapped by this package, use the fully configured AWS SDK v3 client at tools.client (see the programmatic guide for examples).

Quick start (CLI)

aws-api-gateway-tools aws api-gateway flush-cache
aws-api-gateway-tools aws api-gateway pull-keys --key-names '$API_KEY_A' '$API_KEY_B'
Copy

Notes:

• Relevant flags support $VAR expansion evaluated at action time against { ...process.env, ...ctx.dotenv } (ctx.dotenv wins).

AWS X-Ray capture (optional)

X-Ray support is guarded:

• Default behavior is xray: 'auto': capture is enabled only when AWS_XRAY_DAEMON_ADDRESS is set.
• To enable capture, install the optional peer dependency:
  • aws-xray-sdk
• In auto mode, if AWS_XRAY_DAEMON_ADDRESS is set but aws-xray-sdk is not installed, construction throws.

Config defaults (getdotenv.config.*)

If you embed the plugin in your own get-dotenv host (or use the shipped CLI), you can provide safe defaults in config under plugins['aws/api-gateway']:

{
  "plugins": {
    "aws/api-gateway": {
      "apiId": "$API_ID",
      "apiName": "$API_NAME",
      "stageName": "$STAGE_NAME",
      "templateExtension": "template",
      "pullKeys": { "to": "env:private", "delimiter": ", " }
    },
  },
}
Copy

See the api-gateway plugin guide for supported config keys and CLI behavior.

Built for you with ❤️ on Bali! Find more great tools & templates on my GitHub Profile.