Search⌘ K
AI Features
Home
Courses
AWS API Gateway: The Unsung Warrior

Query Parameters

Explore how query parameters work in AWS API Gateway and learn to map incoming parameters to target APIs. This lesson guides you through setting up and integrating query parameters, using practical examples to customize API requests.

We'll cover the following...

What's a query parameter?

Consider the URL, https://example.com?arg1=val1&arg2=val2. Here, arg1 and arg2 are called query parameters. We need query parameter integration in two scenarios.

  • The URL invoking our API contains query parameters that should pass into the target API.

  • The URL of the target API requires some query parameters.

API Gateway enables either of them. When we integrate the requests, we can change the query parameters to get the required mapping.

Example

Let’s check out an example to see how this works. Agify.io has a free public API that can guess a person's age from the name. We can’t expect accurate results from such an API. However, we can use it to test our API integration. For example, GET https://api.agify.io?name=meelad gives us a JSON response {"name": "meelad", "age": 29, "count": 21}

Let’s create a new API with the API Gateway that integrates with this API.

#!/bin/sh -v

# -----------------------------------------------------------------
# Configure the AWS CLI to let it communicate with your account
# -----------------------------------------------------------------
aws configure set aws_access_key_id $aws_access_key_id
aws configure set aws_secret_access_key $aws_secret_access_key
aws configure set region us-east-1

# -----------------------------------------------------------------
# Delete any old deployments
# -----------------------------------------------------------------
# 1. Trigger CloudFormation stack delete
# 2. Wait for the stack to be deleted 
aws cloudformation delete-stack --stack-name  EducativeCourseApiGateway
aws cloudformation wait stack-delete-complete --stack-name EducativeCourseApiGateway


# -----------------------------------------------------------------
# External API, no Lambda function. Initiate the CloudFormation deployment.
# -----------------------------------------------------------------
aws cloudformation deploy \
    --template-file template.yml \
    --stack-name EducativeCourseApiGateway \
    --capabilities CAPABILITY_NAMED_IAM \
    --parameter-overrides DeployId="$RAND" SourceCodeBucket="educative.${bucket}" \
    --region us-east-1

# -----------------------------------------------------------------
# Get the API ID of the Rest API we just created.
# -----------------------------------------------------------------
apiId=`aws cloudformation list-stack-resources --stack-name EducativeCourseApiGateway | jq -r ".StackResourceSummaries[1].PhysicalResourceId"`
echo "API ID: $apiId"

# -----------------------------------------------------------------
# This is the URL for the API we just created
# -----------------------------------------------------------------
url="https://${apiId}.execute-api.us-east-1.amazonaws.com/v1/query?n=vikas"
echo $url

# -----------------------------------------------------------------
# Invoke the URL to test the response
# -----------------------------------------------------------------
curl $url
Integrating query parameters

Click "Run" to deploy and test the API. If all goes well, the script invokes the new API we developed, which invokes the Agify API to get this response from the API.

Javascript (babel-node)
{"name":"vikas","age":43,"count":2386}

Let’s try to understand the code:

  • In line 18-22 template.yml defines a query parameter in the incoming API request. The name of the parameter is n and its type is string

  • In Line 30-32 template.yml specifies the HTTP integration of this API to the external URL, https://api.agify.io.

  • In Line 36-37 template.yml define the query parameter mapping. The method.request.querystring.n is the query string parameter n in the input URL. We map it to integration.request.querystring.name the query string parameter of the target API.

  • In Line 38 run.sh builds the API URL that we use to test the API. The https://${apiId}.execute-api.us-east-1.amazonaws.com/v1/query?n=vikas. input request maps to a call to the target API, https://api.agify.io/?name=vikas. The query parameter, n, in the input maps into the parameter, name, in the output.

Web console

Let’s look at the AWS console to see how this looks in the UI. Open the API Gateway console and open the EducativeRestAPI to check its details. Open the method request

Here, we can see the query string parameter, n, declared optional string data. The "Required" checkbox is unchecked because we haven’t made it a required parameter. Similarly, caching is disabled, so each request is evaluated independently.

Next, open the “Integration request” tab to see how AWS configured the HTTP integration to the external API.

Note that the integration type is set to HTTP, HTTP method is set to GET, and the endpoint URL is the target API that we want to invoke. Note that the endpoint URL doesn’t have any query parameters defined in the configuration. The data mapping identifies them, as implemented elsewhere.

Scrolling down a bit shows the query string parameters.

Note here that the name parameter in the target URL is built from the input query string parameter, n, defined by method.request.querystring.n.

The method request section identifies query string parameters in the incoming URL. The integration request section maps it to the query string parameters in the target URL. The parameter names are in the source, and the target URLs are independent. In the example above, n in the input maps to name in the output.