serverless-api-gateway-caching
Advanced tools
A plugin for the serverless framework which helps with configuring caching for API Gateway endpoints.
A plugin for the serverless framework which helps with configuring caching for API Gateway endpoints.
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
You can use the apiGatewayCaching section ("global settings") to quickly configure cache time-to-live, data encryption and per-key cache invalidation for all endpoints. The settings are inherited by each endpoint for which caching is enabled.
Cache clusterSize can only be specified under global settings, because there's only one cluster per API Gateway stage.
plugins:
- serverless-api-gateway-caching
custom:
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".
If you need a specific endpoint to override any of the global settings, you can add them like this:
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true
ttlInSeconds: 300
functions:
get-cat-by-paw-id:
handler: rest_api/cat/get/handler.handle
events:
- http:
path: /cats/{pawId}
method: get
caching:
enabled: true
ttlInSeconds: 3600 # overrides the global setting for ttlInSeconds
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
ANY, caching will be enabled only for the GET 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 a warning 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. Please note that cache key parameters are case sensitive.
Suppose the configuration looks like this:
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true
functions:
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.querystring.catName
When the endpoint is hit, API Gateway will create cache entries based on the pawId path parameter and the catName query string parameter. For instance:
GET /cats/4 will create a cache entry for pawId=4 and catName as undefined.GET /cats/34?catName=Toby will create a cache entry for pawId=34 and catName=Toby.GET /cats/72?catName=Dixon&furColour=white will create a cache entry for pawId=72 and catName=Dixon, but will ignore the furColour query string parameter. That means that a subsequent request to GET /cats/72?catName=Dixon&furColour=black will return the cached response for pawId=72 and catName=Dixon.When an endpoint varies its responses based on values found in the path, query string or header, you can specify all the parameter names as cache key parameters:
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true
functions:
get-cats:
handler: rest_api/cat/get/handler.handle
events:
- http:
path: /cats/{city}/{shelterId}/
method: get
caching:
enabled: true
cacheKeyParameters:
- name: request.path.city
- name: request.path.shelterId
- name: request.querystring.breed
- name: request.querystring.furColour
- name: request.header.Accept-Language
When you specify a catch-all route that intercepts all requests to the path and routes them to the same function, you can also configure the path as a cache key parameter. In this example:
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true
functions:
get-cats:
handler: rest_api/cat/get/handler.handle
events:
- http:
path: /cats/{proxy+}
method: get
caching:
enabled: true
cacheKeyParameters:
- name: request.path.proxy
API Gateway will create cache entries like this:
GET /cats/toby/ will create a cache entry for proxy=tobyGET /cats/in/london will create an entry for proxy=in/londonGET /cats/in/london?named=toby will only create an entry for proxy=in/london, ignoring the query string. Note, however, that you can also add the named query string parameter as a cache key parameter and it will cache based on that value as well.When the cache key parameter is the entire request body, you must set up a mapping from the client method request to the integration request.
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true
functions:
# Cache responses for POST requests based on the whole request body
cats-graphql:
handler: graphql/handler.handle
events:
- http:
path: /graphql
method: post
caching:
enabled: true
cacheKeyParameters:
- name: integration.request.header.bodyValue
mappedFrom: method.request.body
When the cache key parameter is part of the request body, you can define a JSONPath expression. The following example uses as cache key parameter the cities[0].petCount value from the request body:
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true
functions:
# Cache responses for POST requests based on a part of the request body
cats-graphql:
handler: graphql/handler.handle
events:
- http:
path: /graphql
method: post
caching:
enabled: true
cacheKeyParameters:
- name: integration.request.header.petCount
mappedFrom: method.request.body.cities[0].petCount
Cache key parameters coming from multi-value query strings and multi-value headers are currently not supported.
Setting apiGatewayIsShared to true means that no changes are applied to the root caching configuration of the API Gateway. However, ttlInSeconds, dataEncryption and perKeyInvalidation are still applied to all functions, unless specifically overridden.
If the shared API Gateway is in a different CloudFormation stack, you'll need to export its RestApiId and pass it to the plugin via the optional restApiId setting. If the gateway is part of the stack you are deploying, you don't need to do this; the plugin will find the RestApiId automatically.
If the shared gateway has a default base path that is not part of your endpoint configuration, you can specify it using the optional basePath setting.
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true
apiGatewayIsShared: true
restApiId: ${cf:api-gateway-${self:provider.stage}.RestApiId}
basePath: /animals
clusterSize: '0.5'
ttlInSeconds: 300
dataEncrypted: true
perKeyInvalidation:
requireAuthorization: true
handleUnauthorizedRequests: Ignore
In the project hosting the main API Gateway deployment:
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true # create an API cache
ttlInSeconds: 0 # but don't cache responses by default (individual endpoints can override this)
In a project that references that API Gateway:
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true # enables caching for endpoints in this project (each endpoint must also set caching: enabled to true)
apiGatewayIsShared: true # makes sure the settings on the Main API Gateway are not changed
restApiId: ${cf:api-gateway-${self:provider.stage}.RestApiId}
basePath: /animals
functions:
# caching disabled, it must be explicitly enabled
adoptCat:
handler: adoptCat.handle
events:
- http:
path: /cat/adoption
method: post
getCats:
handler: getCats.handle
events:
- http:
path: /cats
method: get
caching:
enabled: true # enables caching for this endpoint
You can use this feature to configure caching for endpoints which are defined in CloudFormation and not as serverless functions.
If your serverless.yml contains, for example, a HTTP Proxy like this:
resources:
Resources:
ProxyResource:
Type: AWS::ApiGateway::Resource
Properties:
ParentId:
Fn::GetAtt:
- ApiGatewayRestApi # the default REST API logical ID
- RootResourceId
PathPart: serverless # the endpoint in your API that is set as proxy
RestApiId:
Ref: ApiGatewayRestApi
ProxyMethod:
Type: AWS::ApiGateway::Method
Properties:
ResourceId:
Ref: ProxyResource
RestApiId:
Ref: ApiGatewayRestApi
HttpMethod: GET
AuthorizationType: NONE
MethodResponses:
- StatusCode: 200
Integration:
IntegrationHttpMethod: POST
Type: HTTP
Uri: http://serverless.com # the URL you want to set a proxy to
IntegrationResponses:
- StatusCode: 200
Then you can configure caching for it like this:
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true
additionalEndpoints:
- method: GET
path: /serverless
caching:
enabled: true # it must be specifically enabled
ttlInSeconds: 1200 # if not set, inherited from global settings
dataEncrypted: true # if not set, inherited from global settings
A function with several endpoints:
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true
functions:
get-cat-by-pawId:
handler: rest_api/cat/get/handler.handle
events:
- http:
path: /cats/{pawId}
method: get
caching:
enabled: true
cacheKeyParameters:
- name: request.path.pawId
- name: request.querystring.includeAdopted
- name: request.header.Accept-Language
- http:
path: /cats
method: get
caching:
enabled: true
cacheKeyParameters:
- name: request.querystring.pawId
- name: request.querystring.includeAdopted
- name: request.header.Accept-Language
Cache key parameters found in the body and as querystring:
plugins:
- serverless-api-gateway-caching
custom:
apiGatewayCaching:
enabled: true
functions:
list-cats:
handler: rest_api/cat/get/handler.handle
events:
- http:
path: /cats
method: post
caching:
enabled: true
cacheKeyParameters:
- name: request.querystring.catName
- name: integration.request.header.furColour
mappedFrom: method.request.body.furColour
FAQs
A plugin for the serverless framework which helps with configuring caching for API Gateway endpoints.
The npm package serverless-api-gateway-caching receives a total of 25,699 weekly downloads. As such, serverless-api-gateway-caching popularity was classified as popular.
We found that serverless-api-gateway-caching demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Fluent Assertions is facing backlash after dropping the Apache license for a commercial model, leaving users blindsided and questioning contributor rights.
Research
Security News
Socket researchers uncover the risks of a malicious Python package targeting Discord developers.
Security News
The UK is proposing a bold ban on ransomware payments by public entities to disrupt cybercrime, protect critical services, and lead global cybersecurity efforts.