Serverless — enable caching on query string parameters in API Gateway

Since I start­ed work­ing at Yubl less than 2 weeks ago, I have been doing a lot of work with Ama­zon API Gate­way & Lamb­da with the help of the Server­less frame­work. So far that expe­ri­ence has been real­ly great.

One lit­tle caveat I ran into was that, it wasn’t clear on how to enable caching on query string and request path para­me­ters. For instance, if I declare in my s-function.json file that my API Gate­way end­point has a query string para­me­ter called query:

"requestParameters": {
    "integration.request.querystring.query": "method.request.querystring.query"

When the end­point is deployed, you will see in the API Gate­way con­sole that ‘Caching’ is not enabled:


Which means when I enable caching on my deployed stage, the query string para­me­ter would not be tak­en into account.


Users vis­it­ing the fol­low­ing URLs would get the same cached response back:

That’s obvi­ous­ly not OK.

Sad­ly, the same applied to request path para­me­ters too:

"path": "yubl/{query}",
"method": "GET",
"type": "AWS",


Thank­ful­ly, the guys work­ing on Server­less has been very active­ly in respond­ing to their issues page and one of the team mem­bers picked up my tick­et and offered some insight on how to make this work.

API Gateway’s own doc­u­men­ta­tion eludes to two Inte­gra­tion para­me­ters called cacheName­space and cacheKey­Pa­ra­me­ters. Although, to say they’re poor­ly doc­u­ment­ed would be an under­state­ment…


So, after some fid­dling around:

  1. cre­ate an API with cached query string param
  2. deploy it
  3. export as Swag­ger + API Gate­way Exten­sions
  4. inspect the JSON to see what val­ue is out­putted for cacheName­space and cacheKey­Pa­ra­me­ters


Inter­est­ing­ly, when I put the above val­ue — “method.input.params.query” — in my s-function.json I get the fol­low­ing error dur­ing deploy­ment:

Invalid cache key para­me­ter spec­i­fied

what did work though, is the same val­ue I had spec­i­fied in my request­Pa­ra­me­ters dic­tio­nary, which is “method.request.querystring.query” in this case. ie

"requestParameters": {
    "integration.request.querystring.query": "method.request.querystring.query"
"cacheKeyParametes" [

How­ev­er, apply­ing the same approach­es to request path para­me­ters proved fruit­less.. I guess we’ll just have to wait for offi­cial doc­u­men­ta­tion to be updat­ed to see how it should work, which should be soon by the sound of things!

UPDATE 17/08/2016 : short­ly after I post­ed this I did find a way to get request path para­me­ters work­ing too (which might have been a result of a Server­less update, though I can’t remem­ber now). For request path para­me­ters you need some­thing along the lines of:

"requestParameters": {
    "integration.request.path.otherUserId": ""
"cacheKeyParametes" [

Like what you’re read­ing? Check out my video course Pro­duc­tion-Ready Server­less and learn the essen­tials of how to run a server­less appli­ca­tion in pro­duc­tion.

We will cov­er top­ics includ­ing:

  • authen­ti­ca­tion & autho­riza­tion with API Gate­way & Cog­ni­to
  • test­ing & run­ning func­tions local­ly
  • CI/CD
  • log aggre­ga­tion
  • mon­i­tor­ing best prac­tices
  • dis­trib­uted trac­ing with X-Ray
  • track­ing cor­re­la­tion IDs
  • per­for­mance & cost opti­miza­tion
  • error han­dling
  • con­fig man­age­ment
  • canary deploy­ment
  • VPC
  • secu­ri­ty
  • lead­ing prac­tices for Lamb­da, Kine­sis, and API Gate­way

You can also get 40% off the face price with the code ytcui. Hur­ry though, this dis­count is only avail­able while we’re in Manning’s Ear­ly Access Pro­gram (MEAP).