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.

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.

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

Configuring per-endpoint settings

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
            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.

Quick overview of how cache entries are created

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=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.

Cache key parameters from the path, query string and header

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

Caching catch-all path parameters

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=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.

Cache key parameters from the body

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

Limitations

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.

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

Example of configuring an API Gateway with endpoints scattered across multiple serverless projects

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

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:

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

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.

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:

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