How to Use Query Parameters in AWS API Gateway

In AWS API Gateway, you use method request to define query parameters and map them to your backend integration. Query parameters are accessed by defining them in the API Gateway method and then using mapping templates or direct passthrough to forward them to your backend service.

Syntax

To use query parameters in API Gateway, you define them in the Method Request section under URL Query String Parameters. Then, in the Integration Request, you map these parameters to your backend using mapping templates or passthrough.

Key parts:

• {paramName}: The name of the query parameter you expect.
• method.request.querystring.paramName: Reference to the query parameter in mapping templates.
• Integration Request Mapping Template: Transforms or forwards query parameters to backend.

plaintext

GET /resource?param1=value1&param2=value2

Method Request:
  URL Query String Parameters:
    param1: required
    param2: optional

Integration Request Mapping Template (Velocity Template Language):
{
  "param1": "$input.params('param1')",
  "param2": "$input.params('param2')"
}

Example

This example shows how to configure an API Gateway GET method to accept query parameters user and age, then forward them as JSON to a Lambda function.

json

{
  "swagger": "2.0",
  "paths": {
    "/hello": {
      "get": {
        "parameters": [
          {
            "name": "user",
            "in": "query",
            "required": true,
            "type": "string"
          },
          {
            "name": "age",
            "in": "query",
            "required": false,
            "type": "integer"
          }
        ],
        "x-amazon-apigateway-integration": {
          "type": "aws_proxy",
          "httpMethod": "POST",
          "uri": "arn:aws:apigateway:region:lambda:path/2015-03-31/functions/arn:aws:lambda:region:account-id:function:HelloFunction/invocations"
        }
      }
    }
  }
}

Output

When you call GET /hello?user=Alice&age=30, API Gateway passes {"user":"Alice","age":30} to the Lambda function.

Common Pitfalls

Common mistakes when using query parameters in API Gateway include:

• Not defining query parameters in the Method Request, causing them to be ignored.
• Forgetting to map query parameters in Integration Request, so backend does not receive them.
• Using incorrect parameter names or case sensitivity issues.
• Assuming query parameters are automatically passed without configuration.

Always verify parameters are declared and mapped properly.

plaintext

Wrong way (missing parameter declaration):
GET /resource?foo=bar

Method Request:
  No query parameters defined

Result: Backend does not receive 'foo'

Right way:
Method Request:
  URL Query String Parameters:
    foo: required

Integration Request:
  Map 'foo' to backend input

Quick Reference

Step	Description
Define Query Parameters	Add parameters in Method Request under URL Query String Parameters.
Map Parameters	Use Integration Request mapping templates or passthrough to send parameters to backend.
Test API	Call API with query parameters and verify backend receives them.
Handle Missing Params	Set parameters as required or optional as needed.
Use Correct Names	Parameter names are case-sensitive and must match exactly.

Key Takeaways

Always declare query parameters in the Method Request to make API Gateway recognize them.

Map query parameters in the Integration Request to forward them to your backend service.

Query parameter names are case-sensitive and must match between client and API Gateway.

Use mapping templates to transform or format query parameters before sending to backend.

Test your API calls with query parameters to ensure correct backend behavior.