A plugin for the serverless framework which helps with configuring caching for API Gateway endpoints.
- If you enable caching globally, it does NOT automatically enable caching for your endpoints - you have to be explicit about which endpoints should have caching enabled. However, disabling caching globally disables it across endpoints.
- If you don't specify
ttlInSeconds
andperKeyInvalidation
for an endpoint which has caching enabled, these settings are inherited from global settings. clusterSize
configuration is only allowed as global setting in AWS, so this parameter must be configured in the global section and will be ignored if it is found in the endpoint configuration level.- For HTTP method
ANY
, caching will be enabled only for theGET
method and disabled for the other methods.
If you don't configure per-key cache invalidation authorization, by default it is required. You can configure how to handle unauthorized requests to invalidate a cache key using the options:
Ignore
- ignores the request to invalidate the cache key.IgnoreWithWarning
- ignores the request to invalidate and adds awarning
header in the response.Fail
- fails the request to invalidate the cache key with a 403 response status code.
You would define these for endpoints where the response varies according to one or more request parameters. API Gateway creates entries in the cache keyed based on them. Note that cache key parameters are case sensitive. Specifying where the request parameters can be found:
- request.path.PARAM_NAME
- request.querystring.PARAM_NAME
- request.multivaluequerystring.PARAM_NAME
- request.header.PARAM_NAME
- request.multivalueheader.PARAM_NAME
I don't currently know of a way to define cache key parameters based on the request.body
or request.body.JSONPath_EXPRESSION
, which should theoretically be possible according to AWS Documentation on request parameter mapping. See this issue for details.
plugins:
- serverless-api-gateway-caching
custom:
# Enable or disable caching globally
apiGatewayCaching:
enabled: true
functions:
# Responses are cached
list-all-cats:
handler: rest_api/cats/get/handler.handle
events:
- http:
path: /cats
method: get
caching:
enabled: true
# Responses are *not* cached
update-cat:
handler: rest_api/cat/post/handler.handle
events:
- http:
path: /cat
method: post
# Responses are cached based on the 'pawId' path parameter and the 'Accept-Language' header
get-cat-by-paw-id:
handler: rest_api/cat/get/handler.handle
events:
- http:
path: /cats/{pawId}
method: get
caching:
enabled: true
cacheKeyParameters:
- name: request.path.pawId
- name: request.header.Accept-Language
# Responses are cached based on the 'breed' query string parameter and the 'Accept-Language' header
get-cats-by-breed:
handler: rest_api/cat/get/handler.handle
events:
- http:
path: /cats
method: get
caching:
enabled: true
cacheKeyParameters:
- name: request.querystring.breed
- name: request.header.Accept-Language
Cache time to live, invalidation settings and data encryption are applied to all functions, unless specifically overridden.
plugins:
- serverless-api-gateway-caching
custom:
# Enable or disable caching globally
apiGatewayCaching:
enabled: true
clusterSize: '0.5' # defaults to '0.5'
ttlInSeconds: 300 # defaults to the maximum allowed: 3600
dataEncrypted: true # defaults to false
perKeyInvalidation:
requireAuthorization: true # default is true
handleUnauthorizedRequests: Ignore # default is "IgnoreWithWarning"
Configuring per-function cache time to live, cache invalidation strategy, cache key parameters and cache data encryption
plugins:
- serverless-api-gateway-caching
custom:
# Enable or disable caching globally
apiGatewayCaching:
enabled: true
functions:
# Responses are cached based on the 'pawId' path parameter and the 'Accept-Language' header
get-cat-by-paw-id:
handler: rest_api/cat/get/handler.handle
events:
- http:
path: /cats/{pawId}
method: get
caching:
enabled: true
ttlInSeconds: 3600
dataEncrypted: true # default is false
perKeyInvalidation:
requireAuthorization: true # default is true
handleUnauthorizedRequests: Fail # default is "IgnoreWithWarning"
cacheKeyParameters:
- name: request.path.pawId
- name: request.header.Accept-Language
No modifications will be applied to the root caching configuration of the api gateway,
Cache time to live, invalidation settings and data encryption are applied to all functions, unless specifically overridden.
plugins:
- serverless-api-gateway-caching
custom:
# Enable or disable caching globally
apiGatewayCaching:
enabled: true
apiGatewayIsShared: true
clusterSize: '0.5' # defaults to '0.5'
ttlInSeconds: 300 # defaults to the maximum allowed: 3600
dataEncrypted: true # defaults to false
perKeyInvalidation:
requireAuthorization: true # default is true
handleUnauthorizedRequests: Ignore # default is "IgnoreWithWarning"