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" [

Liked this post? Why not support me on Patreon and help me get rid of the ads!