Registry / aws / serverless-api-gateway-caching

serverless-api-gateway-caching

library1.11.0jsnpmunverified

The `serverless-api-gateway-caching` plugin for the Serverless Framework simplifies the configuration of caching for AWS API Gateway REST API endpoints. Its current stable version is 1.11.0. This plugin allows developers to define caching settings both globally for an API Gateway stage and granularly for individual endpoints, including time-to-live (TTL), data encryption, and cache key parameters. It provides fine-grained control over which request elements (path, header, query string) contribute to the cache key. A crucial differentiator is its explicit support for *only* REST API Gateway, as AWS HTTP API does not support native caching at this time. Releases are regular, often driven by bug fixes and minor feature enhancements, making it an actively maintained tool for optimizing API performance and reducing backend load for Serverless applications.

aws devops

npm install serverless-api-gateway-caching

github ↗package ↗

INSTALL

IMPORT

SIG · SERVERLESS-API-GAT

serverless-api-gateway-caching

awsjavascriptv1.11.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

This `serverless.yml` configuration demonstrates how to enable the `serverless-api-gateway-caching` plugin, define global caching settings for an API Gateway stage, and then apply and override those settings for specific REST API endpoints, including configuring custom cache key parameters.

plugins: - serverless-api-gateway-caching custom: apiGatewayCaching: # Global settings for API Gateway caching enabled: true clusterSize: '0.5' # defaults to '0.5', determines cache capacity ttlInSeconds: 300 # defaults to 3600, max allowed dataEncrypted: true # defaults to false perKeyInvalidation: requireAuthorization: true # default is true handleUnauthorizedRequests: Ignore # default is "IgnoreWithWarning" endpointsInheritCloudWatchSettingsFromStage: true # default is true functions: # Example: An endpoint with caching enabled list-all-cats: handler: rest_api/cats/get/handler.handle events: - http: path: /cats method: get caching: enabled: true # Explicitly enable caching for this endpoint ttlInSeconds: 600 # Override global TTL for this endpoint # Example: An endpoint with caching enabled and custom cache key parameters get-cat-by-paw-id: handler: rest_api/cat/get/handler.handle events: - http: path: /cats/{pawId} method: get caching: enabled: true # Cache responses based on path parameter 'pawId' and 'Accept-Language' header cacheKeyParameters: - name: request.path.pawId - name: request.header.Accept-Language

Debug

Known issues

gotchaThis plugin explicitly supports only AWS API Gateway REST APIs. It does not work with HTTP APIs because AWS HTTP API currently lacks native caching capabilities. Deploying with an HTTP API will not configure caching.

fix

Ensure your Serverless `http` events define `rest` APIs, not `http` APIs. This plugin is not applicable for HTTP APIs.

affects: >=1.0.0

gotchaEnabling `apiGatewayCaching.enabled: true` globally does not automatically enable caching for all your endpoints. You must explicitly set `caching: enabled: true` under each individual `http` event that you wish to cache. Global settings are inherited by enabled endpoints, but not forced upon them.

fix

For each endpoint requiring caching, add `caching: enabled: true` within its `http` event configuration in `serverless.yml`.

affects: >=1.0.0

breakingThe default behavior for cache key parameters changed. Previously, parameters were implicitly considered 'required' by default. As of 1.10.4, cache key parameters are no longer 'required' by default, which may alter caching behavior for existing configurations that relied on the previous implicit default without explicitly setting `required: true`.

fix

Review existing `cacheKeyParameters` configurations. If a parameter should be required for cache key generation, explicitly add `required: true` to its definition, e.g., `- name: request.path.pawId
  required: true`.

affects: >=1.10.4

breakingThe default value of `Method RequestParameters` changed from an empty object `{}` to `true`. This change in default behavior in version 1.10.3 could affect how API Gateway handles method request parameters if not explicitly configured otherwise.

fix

If your API Gateway methods relied on the previous default `{}` for `Method RequestParameters`, explicitly define your desired `method.request.parameters` to match the intended behavior in your `serverless.yml`.

affects: >=1.10.3

gotchaConfiguring cache key parameters, especially `request.headers.Authorization` or headers with differing casing (e.g., 'authorization' vs 'Authorization'), previously caused `Internal Server Error` responses. This was fixed in v1.8.1, but users on older versions may still encounter this.

fix

Upgrade to version 1.8.1 or newer. When defining `cacheKeyParameters` for headers, ensure consistent casing with how API Gateway expects them or as they are received.

affects: <1.8.1

Errors

Common errors & fixes

Error: The plugin 'serverless-api-gateway-caching' does not support HTTP API. Only REST API is supported.

Attempting to use the plugin with a Serverless service configured for HTTP API Gateway.

fix

The plugin is only compatible with AWS API Gateway REST APIs. Ensure your `serverless.yml` uses `rest` for `http` events or switch to a REST API if currently using HTTP API.

API Gateway caching is not working, even after setting `apiGatewayCaching.enabled: true` in `custom` section.

Global caching configuration only enables the cache cluster at the stage level. Individual endpoints still need explicit activation.

fix

For each specific HTTP endpoint you wish to cache, you must add `caching: enabled: true` within its event configuration in `serverless.yml`.

Internal Server Error when using specific headers like 'Authorization' as cache key parameters.

In versions prior to 1.8.1, there was an issue with case sensitivity and special headers (like Authorization) causing API Gateway to return 500 errors if used as `cacheKeyParameters`.

fix

Upgrade `serverless-api-gateway-caching` to version 1.8.1 or higher. Ensure correct casing for header names if this issue persists.

Error: Cannot read properties of undefined (reading 'someSetting') related to uninitialised settings during deployment.

Older versions of the plugin (prior to 1.10.2) could encounter errors if certain settings were not explicitly initialized, leading to `undefined` property access.

fix

Upgrade to version 1.10.2 or newer to resolve issues with uninitialised settings. Review your `apiGatewayCaching` configuration to ensure all necessary properties are defined.

Upgrade

Version history

1.11.0latest on npm

Audit

Dependencies

serverlessrequiredThis package is a plugin for the Serverless Framework and requires the framework to be installed as a peer dependency.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/DianaIonita/serverless-api-gateway-caching ↗

packagehttps://www.npmjs.com/package/serverless-api-gateway-caching ↗