HTTP Integration

Understand the concept of HTTP integration in AWS API Gateway REST API, along with an example.

We'll cover the following

Public APIs

Public APIs are a part of any sizable application. Nobody can develop everything themselves, and there are many utility APIs that we can use with a simple HTTP call.

Google, H2O, RapidAPI, and others provide many public APIs for our applications. Moreover, many of these are reputable organizations, and we can trust them for the accuracy and consistency of the API. Therefore, using them rather than creating our implementation for the same task makes sense.

The codebase can be challenging when we have too many external APIs in our application. If we have these APIs called from a web application, it can be a significant security risk. That’s because most of these APIs use simple API keys for authentication. It’s easy for anyone to identify these keys and abuse the API.

HTTP integration

HTTP integration solves such problems. It allows us to map the API to an external HTTP URL, and in the process, we can also alter the payload and headers.

We can create a resource in the REST API on API Gateway. Then, we can map it to the public API. While doing so, we can alter the request header to include the API key.

The API key remains a secret, and security isn’t compromised, as API Gateway provides us with several options for the safety of the API.

We can manage all external APIs with a single API in our AWS API Gateway. The same authentication can work for each. The API Gateway configuration takes care of each API key URL detail.

Implementation

Let’s implement such an API with HTTP integration.

We can use a free public API. They have a massive collection of jokes. We use API Gateway to invoke the external API with an HTTP integration.

Below is the code. It creates a REST API and adds a joke resource and a GET method. It maps the method to the external HTTP URL.

Press + to interact
x-amazon-apigateway-integration:
  httpMethod: "GET"
  uri: "https://icanhazdadjoke.com"
  type: "http"

That’s quite intuitive, isn’t it? Let’s now check out the full code and deploy it to the AWS account.

#!/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[0].PhysicalResourceId"`
echo "API ID: $apiId"

# -----------------------------------------------------------------
# Deploy the API to a new Stage (We will discuss this in detail in a later chapter)
# -----------------------------------------------------------------
aws apigateway create-deployment --rest-api-id $apiId --stage-name v1 --description 'Deployed from CLI' 

# -----------------------------------------------------------------
# Give it some time to settle down
# -----------------------------------------------------------------
sleep 30

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

# -----------------------------------------------------------------
# Invoke the URL to test the response
# -----------------------------------------------------------------
curl $url
HTTP integration with external API

Click "Run" to deploy and test the API. The above script invokes the API and displays the result if the deployment is complete.

Click “Run” to deploy and test the API. The script above invokes the API and displays the result if the deployment is complete.

Note lines 16 and 26–28 in the template.yml file.

  • Line 16 defines the resource/path joke used to invoke the API.
  • Line 26 defines the HTTP method used to invoke the API. In this case, it’s GET.
  • Line 27 defines the target URL.
  • Line 28 defines the integration type, HTTP.

Run the code below to check the status of the deployment.

Web console

Check out the web console to see what we’ve done there. Now we know where to go. Navigate to the “AWS Console” -> “API Gateway” -> “EducativeRestAPI.” Check the joke resource and the GET method in there.

Finally, click on the “Integration Request.”

Press + to interact
HTTP integration with external API
HTTP integration with external API

We now have the HTTP integration with the endpoint URL set to the target API.

Utility

As we discussed before, this has immense potential. For example, we can add headers and alter payload in the API Gateway along with the HTTP integration.

Such integration helps with encapsulation and modularity while hardening architecture security.