Serverless – enable caching on query string parameters in API Gateway

Yan Cui

I help clients go faster for less using serverless technologies.

This article is brought to you by

Is your CI build step taking too long? Try Depot for free today and experience up to 40x faster build speed!

Unlock faster CI for FREE

Since I started working at Yubl less than 2 weeks ago, I have been doing a lot of work with Amazon API Gateway & Lambda with the help of the Serverless framework. So far that experience has been really great.

One little caveat I ran into was that, it wasn’t clear on how to enable caching on query string and request path parameters. For instance, if I declare in my s-function.json file that my API Gateway endpoint has a query string parameter called query:

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

When the endpoint is deployed, you will see in the API Gateway console that ‘Caching’ is not enabled:


Which means when I enable caching on my deployed stage, the query string parameter would not be taken into account.


Users visiting the following URLs would get the same cached response back:

That’s obviously not OK.

Sadly, the same applied to request path parameters too:

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


Thankfully, the guys working on Serverless has been very actively in responding to their issues page and one of the team members picked up my ticket and offered some insight on how to make this work.

API Gateway’s own documentation eludes to two Integration parameters called cacheNamespace and cacheKeyParameters. Although, to say they’re poorly documented would be an understatement…


So, after some fiddling around:

  1. create an API with cached query string param
  2. deploy it
  3. export as Swagger + API Gateway Extensions
  4. inspect the JSON to see what value is outputted for cacheNamespace and cacheKeyParameters


Interestingly, when I put the above value – “method.input.params.query” – in my s-function.json I get the following error during deployment:

Invalid cache key parameter specified

what did work though, is the same value I had specified in my requestParameters dictionary, which is “method.request.querystring.query” in this case. ie

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

However, applying the same approaches to request path parameters proved fruitless.. I guess we’ll just have to wait for official documentation to be updated to see how it should work, which should be soon by the sound of things!

UPDATE 17/08/2016 : shortly after I posted this I did find a way to get request path parameters working too (which might have been a result of a Serverless update, though I can’t remember now). For request path parameters you need something along the lines of:

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

Whenever you’re ready, here are 4 ways I can help you:

  1. Production-Ready Serverless: Join 20+ AWS Heroes & Community Builders and 1000+ other students in levelling up your serverless game. This is your one-stop shop for quickly levelling up your serverless skills.
  2. Do you want to know how to test serverless architectures with a fast dev & test loop? Check out my latest course, Testing Serverless Architectures and learn the smart way to test serverless.
  3. I help clients launch product ideas, improve their development processes and upskill their teams. If you’d like to work together, then let’s get in touch.
  4. Join my community on Discord, ask questions, and join the discussion on all things AWS and Serverless.

6 thoughts on “Serverless – enable caching on query string parameters in API Gateway”

  1. Pingback: Javascript – string replace all without Regex |

  2. After an hour of meesing around with Serverless dialect and searching on the web, I got it to work thanks to your article. So, I don’t know if you still need it, but below snippet from s-function.json makes caching parameters available. At least I see them in the console.

    Hope this helps!

    “endpoints”: [
    “path”: “legal/doc”,
    “method”: “GET”,
    “authorizationType”: “none”,
    “apiKeyRequired”: false,
    “requestParameters”: {
    “integration.request.querystring.context” : “method.request.querystring.context”,
    “integration.request.querystring.rkId” : “method.request.querystring.rkId”,
    “integration.request.querystring.poId” : “method.request.querystring.poId”,
    “integration.request.querystring.includeIraManagement” : “method.request.querystring.includeIraManagement”

    “cacheKeyParameters” : [

    “cacheNamespace” : “legaldocs”,

  3. thanks, we did get the request path to work in the end with configurations like this one:

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

  4. Nice. Thanks again. Your post saved me a lot of time! We are actively looking to dump the Serverless framework and go directly to CF and AWS CLI. Things are much easier that way. In the meantime, this is very helpful.

  5. with Serverless 1.0 they’ve revamped the whole thing and going directly to CF themselves, so might be worth holding off doing all that yourself, just my 2 cents

Leave a Comment

Your email address will not be published. Required fields are marked *