How do I configure my API Gateway REST API to pass query string parameters to a backend Lambda function or HTTP endpoint?

Short description

To configure a REST API to pass query string parameters to a backend AWS Lambda function, use a Lambda custom integration.

To pass query string parameters to an HTTP endpoint, use an HTTP custom integration.

Important: Make sure that you supply the input data as the integration request payload. It’s a best practice to use a mapping template to supply the payload. For more information, see Map request and response payloads between method and integration.

Resolution

Passing query string parameters to a backend Lambda function

1.    Open the API Gateway console, and then choose your API.

2.    In the Resources pane, choose the configured HTTP method.

Note: If there’s more than one HTTP method configured for the API, then repeat steps 2 through 15 for each method.

3.    In the Method Execution pane, choose Method Request.

4.    Expand the URL Query String Parameters dropdown list, then choose Add query string.

5.    For the Name field, enter pet, and then choose the check mark icon.

6.    Choose the Required check box.

7.    Choose the Method Execution pane.

8.    Choose Integration Request.

9.    Choose the Mapping Templates dropdown list, and then choose Add mapping template.

10.    For the Content-Type field, enter application/json and then choose the check mark icon.

11.    In the pop-up that appears, choose Yes, secure this integration.

12.    For Request body passthrough, choose When there are no templates defined (recommended).

13.    In the mapping template editor, copy and replace the existing script with the following code:

{
     "pet": "$input.params('pet')"
}

Note: For more information, see the $input variables.

14.    Choose Save, and then choose Deploy the API.

15.    To test the API's new endpoint, run the following curl command:

curl -X GET https://jp58lnf5vh.execute-api.us-west-2.amazonaws.com/dev/lambda-non-proxy?pet=dog

Important: Make sure that the curl command has the query string parameter pet=dog.

Passing query string parameters to an HTTP endpoint

1.    Open the API Gateway console, and then choose your API.

2.    In the Resources pane, choose the configured HTTP method.

Note: If there’s more than one HTTP method configured for the API, then repeat steps two through 10 for each method.

3.    In the Method Execution pane, choose Method Request.

4.    Expand the URL Query String Parameters dropdown list, and then choose Add query string.

5.    For the Name field, enter type, and then choose the check mark icon.

6.    Choose the Method Execution pane.

7.    Choose Integration Request.

8.    Expand the URL Query String Parameters section.

Note: By default, the method request query string parameters are mapped to the like-named integration request query string parameters. To view this, refresh the API Gateway console page. To map a method request parameter to a different integration request parameter, first delete the existing integration request parameter. Then, add a new query string with the desired method request parameter mapping expression.

9.    Choose Save, then choose Deploy the API.

10.    To test the API’s new endpoint, run the following curl command:

curl -X GET https://jp58lnf5vh.execute-api.us-west-2.amazonaws.com/dev/http-endpoint?pet=dog

Important: Make sure that the curl command has the query string parameter pet=dog.

---

Related information

Tutorial: Build a Hello World REST API with Lambda proxy integration

Tutorial: Build an API Gateway REST API with Lambda non-proxy integration

Tutorial: Build a REST API with HTTP proxy integration

Tutorial: Build a REST API with HTTP non-proxy integration