serverless-api-gateway-caching

!npm

Intro

A plugin for the serverless framework which helps with configuring caching for API Gateway endpoints.

Quick Start

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.

``yml
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
`

Only supports REST API

This plugin only supports REST API, because HTTP API does not support API Gateway Caching at the time of this writing. See docs.

Time-to-live, encryption, cache invalidation settings

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.

The setting endpointsInheritCloudWatchSettingsFromStage makes sure that settings like Log Level and whether to Enable detailed CloudWatch metrics are copied over from the stage to each endpoint's settings. It is true by default.

`yml
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".
endpointsInheritCloudWatchSettingsFromStage: true # default is true
`

$3

If you need a specific endpoint to override any of the global settings, you can add them like this:

`yml
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
inheritCloudWatchSettingsFromStage: false # default is true
perKeyInvalidation:
requireAuthorization: true # default is true
handleUnauthorizedRequests: Fail # default is "IgnoreWithWarning"
cacheKeyParameters:
- name: request.path.pawId
- name: request.header.Accept-Language
`

Good to know


* For HTTP method ANY, caching will be enabled only for the GET method and disabled for the other methods.

Per-key cache invalidation

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.

Cache key parameters

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.

$3

Suppose the configuration looks like this:

`yml
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=Dixon will create a cache entry for pawId=34 and catName=Dixon.
- GET /cats/72?catName=Tsunami&furColour=white will create a cache entry for pawId=72 and catName=Tsunami, but will ignore the furColour query string parameter. That means that a subsequent request to GET /cats/72?catName=Tsunami&furColour=black will return the cached response for pawId=72 and catName=Tsunami.

$3


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:

`yml
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
`

$3

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:

`yml
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=toby
- GET /cats/in/london will create an entry for proxy=in/london
- GET /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.




$3

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.

`yml
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:

`yml
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
`

$3

Cache key parameters coming from multi-value query strings and multi-value headers are currently not supported.

Configuring a shared API Gateway

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.

`yml
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
`

$3

In the project hosting the main API Gateway deployment:

`yml
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:

`yml
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
`

Configuring caching settings for endpoints defined in CloudFormation


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:

`yml
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:

`yml
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
`

Configuring caching when the endpoint bypasses lambda and talks to a service like DynamoDb

This example uses the serverless-apigateway-service-proxy plugin which creates the path /dynamodb?id=cat_id.
Caching can be configured using the additionalEndpoints feature. The method and path must match the ones defined as a service proxy. It also supports cache key parameters.

`yml
plugins:
- serverless-api-gateway-caching
- serverless-apigateway-service-proxy

custom:
apiGatewayCaching:
enabled: true
additionalEndpoints:
- method: GET
path: /dynamodb
caching:
enabled: true
ttlInSeconds: 120
cacheKeyParameters:
- name: request.querystring.id

apiGatewayServiceProxies:
- dynamodb:
path: /dynamodb
method: get
tableName: { Ref: 'MyDynamoCatsTable' }
hashKey:
queryStringParam: id # use query string parameter
attributeType: S
action: GetItem
cors: true

resources:
Resources:
MyDynamoCatsTable:
Type: AWS::DynamoDB::Table
Properties:
TableName: my-dynamo-cats
AttributeDefinitions:
- AttributeName: id
AttributeType: S
KeySchema:
- AttributeName: id
KeyType: HASH
`

More Examples

A function with several endpoints:

`yml
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:

`yml
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
``