How to Trigger AWS Lambda from an API Gateway GET Request (Step-by-Step)

Exposing a Lambda function as an HTTP endpoint is one of the most common serverless patterns — yet misconfigured integrations, missing permissions, and route confusion are the top reasons developers hit 500 errors on day one. This guide walks you through creating an API Gateway HTTP API with a GET route that invokes a Lambda function, covering every layer from IAM to testing.

TL;DR

StepWhat You DoKey Detail
1Create the Lambda functionReturn a valid HTTP response object
2Create an HTTP API in API GatewayUse HTTP API (v2), not REST API (v1)
3Create a GET routee.g., GET /hello
4Attach Lambda integrationAWS_PROXY integration type
5Grant invoke permissionResource-based policy on Lambda
6Deploy & testUse the auto-generated invoke URL

Architecture Overview

Before diving into code, understand the request flow. API Gateway acts as the front door — it receives the HTTP GET request, routes it to the correct integration, and proxies the event payload to Lambda.

graph LR Client(["Client Browser / curl"]) APIGW["API Gateway HTTP API v2"] Route["Route GET /hello"] Integration["Lambda Proxy Integration"] Lambda["Lambda Function hello-api"] CWL["CloudWatch Logs"] Client -->|"HTTP GET /hello?name=Engineer"| APIGW APIGW --> Route Route --> Integration Integration -->|"Invoke with event payload"| Lambda Lambda -->|"Structured response object"| Integration Integration -->|"HTTP 200 + JSON body"| Client Lambda -->|"Execution logs"| CWL
  1. Client sends an HTTP GET request to the API Gateway invoke URL.
  2. API Gateway (HTTP API) matches the request to the GET /hello route.
  3. The route's Lambda Proxy Integration forwards the full event context to the Lambda function.
  4. Lambda executes and returns a structured response object.
  5. API Gateway translates the Lambda response back into an HTTP response to the client.
Analogy: Think of API Gateway as a hotel concierge. The client (guest) makes a request at the front desk. The concierge (API Gateway) routes it to the right department (Lambda). The department does the work and hands the result back through the concierge — the guest never interacts with the back office directly.

Step 1: Create the Lambda Function

Your Lambda function must return a response object that API Gateway's proxy integration understands. The required fields are statusCode and body.

🔽 Python Lambda Handler (Click to expand) 
import json

def lambda_handler(event, context):
    # 'event' contains the full HTTP request context
    query_params = event.get("queryStringParameters") or {}
    name = query_params.get("name", "World")

    return {
        "statusCode": 200,
        "headers": {
            "Content-Type": "application/json"
        },
        "body": json.dumps({
            "message": f"Hello, {name}!"
        })
    }

Deploy via AWS CLI:

# 1. Package the function
zip function.zip lambda_function.py

# 2. Create the Lambda function
aws lambda create-function \
  --function-name hello-api \
  --runtime python3.12 \
  --role arn:aws:iam::123456789012:role/lambda-basic-execution-role \
  --handler lambda_function.lambda_handler \
  --zip-file fileb://function.zip \
  --region us-east-1

IAM Role requirement: The execution role (lambda-basic-execution-role) must have at minimum the AWSLambdaBasicExecutionRole managed policy attached, which grants CloudWatch Logs write access.

Step 2: Create the HTTP API

API Gateway offers two API types: REST API (v1) and HTTP API (v2). For simple Lambda proxy integrations, HTTP API is recommended — it is lower latency and lower cost.

aws apigatewayv2 create-api \
  --name hello-http-api \
  --protocol-type HTTP \
  --region us-east-1

Note the ApiId returned in the response — you will need it in subsequent steps. Example: abc1234xyz.

Step 3: Create the Lambda Integration

The integration connects the API route to your Lambda function. HTTP API uses AWS_PROXY as the integration type for Lambda, which passes the full request context as the event payload.

aws apigatewayv2 create-integration \
  --api-id abc1234xyz \
  --integration-type AWS_PROXY \
  --integration-uri arn:aws:lambda:us-east-1:123456789012:function:hello-api \
  --payload-format-version 2.0 \
  --region us-east-1

Note the IntegrationId returned (e.g., xyz9876abc).

Payload Format Version:

  • 2.0 — Recommended for HTTP APIs. Simpler event structure, supports Lambda response format 2.0 (no need to wrap body in JSON string if using the simplified format).
  • 1.0 — Compatible with REST API event format. Use this if migrating from REST API.

Step 4: Create the GET Route

A route maps an HTTP method + path to an integration. Here we map GET /hello to the Lambda integration created above.

aws apigatewayv2 create-route \
  --api-id abc1234xyz \
  --route-key "GET /hello" \
  --target "integrations/xyz9876abc" \
  --region us-east-1

Step 5: Grant API Gateway Permission to Invoke Lambda

This is the most commonly missed step. API Gateway must have explicit permission to invoke your Lambda function via a resource-based policy on the Lambda function itself.

aws lambda add-permission \
  --function-name hello-api \
  --statement-id allow-apigw-invoke \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:us-east-1:123456789012:abc1234xyz/*/*/hello" \
  --region us-east-1

Source ARN breakdown:

SegmentValueMeaning
Serviceexecute-apiAPI Gateway execution service
Regionus-east-1Region of the API
Account123456789012Your AWS Account ID
API IDabc1234xyzYour HTTP API ID
Stage/Method/Path*/*/* or */GET/helloWildcard or specific route

Least Privilege Tip: Use */GET/hello instead of */*/* to restrict the permission to only the specific route and method.

Step 6: Deploy the API (Create a Stage)

HTTP APIs require a stage to be deployed. The $default stage is auto-created with auto-deploy enabled when using the console, but via CLI you must create it explicitly.

aws apigatewayv2 create-stage \
  --api-id abc1234xyz \
  --stage-name "$default" \
  --auto-deploy \
  --region us-east-1

Step 7: Test the Endpoint

Retrieve the invoke URL and test with curl:

# Get the invoke URL
aws apigatewayv2 get-api \
  --api-id abc1234xyz \
  --region us-east-1 \
  --query "ApiEndpoint" \
  --output text

# Output: https://abc1234xyz.execute-api.us-east-1.amazonaws.com

# Test the GET route
curl "https://abc1234xyz.execute-api.us-east-1.amazonaws.com/hello?name=Engineer"

# Expected response:
# {"message": "Hello, Engineer!"}

Request Flow: Sequence Diagram

sequenceDiagram participant C as Client participant AG as API Gateway participant L as Lambda C->>AG: GET /hello?name=Engineer AG->>AG: Match route GET /hello AG->>L: Invoke with HTTP event payload L->>L: Execute lambda_handler L-->>AG: Return statusCode 200 + body AG-->>C: HTTP 200 JSON response
  1. Client sends GET /hello?name=Engineer to the API Gateway endpoint.
  2. API Gateway matches the route and checks the Lambda integration.
  3. API Gateway invokes the Lambda function, passing the full HTTP event as the payload.
  4. Lambda executes the handler and returns a structured response object.
  5. API Gateway translates the response and returns HTTP 200 with the JSON body to the client.

Common Errors & Fixes

ErrorRoot CauseFix
500 Internal Server ErrorLambda response missing statusCodeEnsure handler returns {"statusCode": 200, "body": "..."}
403 ForbiddenMissing resource-based policy on LambdaRun aws lambda add-permission (Step 5)
404 Not FoundRoute key mismatch or stage not deployedVerify route key and deploy the $default stage
Integration not foundWrong IntegrationId in route targetPrefix target with integrations/

Glossary

TermDefinition
HTTP API (v2)The newer, lower-cost API Gateway offering optimized for Lambda and HTTP backends.
AWS_PROXY IntegrationPasses the raw HTTP request as a structured event to Lambda; Lambda controls the full response.
Payload Format VersionDefines the schema of the event object sent to Lambda (1.0 = REST API format, 2.0 = HTTP API format).
Resource-Based PolicyA policy attached to a Lambda function that grants external services (like API Gateway) permission to invoke it.
StageA named reference to a deployment of your API (e.g., $default, prod).

Next Steps

Related Posts

Comments

Post a Comment

Popular posts from this blog

EC2 No Internet Access in Custom VPC: Attaching an Internet Gateway and Fixing Route Tables

Launching an EC2 instance in a custom VPC only to find it cannot reach the internet is one of the most common networking pitfalls in AWS — and it almost always comes down to two missing pieces: an Internet Gateway (IGW) and a correctly configured Route Table. This post walks you through the exact architecture, the root cause, and the precise steps to fix it. TL;DR Step Action Why It Matters 1 Create and attach an Internet Gateway to your VPC Without an IGW, there is no path between your VPC and the public internet 2 Add a 0.0.0.0/0 route pointing to the IGW in your subnet's Route Table The route table is the traffic director — without this entry, outbound packets have nowhere to go 3 Assign a Public IP or Elastic IP to the EC2 instance The IGW performs NAT only for instances with a public IP address 4 Verify Security Group allows outbound traffic Security Groups are stateful firewalls; outbound rules...
Read more

EC2 SSH Connection Timeout: The Exact Security Group Rules You Need to Fix It

You've launched a fresh EC2 instance, fired up your terminal, and run ssh ec2-user@<your-ip> — only to watch the cursor hang until Connection timed out kills your hope. This is one of the most common EC2 onboarding blockers, and it almost always traces back to a misconfigured Security Group inbound rule. TL;DR Check What to Verify Correct Value Protocol Security Group inbound rule protocol TCP Port Destination port in the inbound rule 22 Source Allowed source CIDR or IP Your public IP (e.g., 203.0.113.10/32 ) or 0.0.0.0/0 for testing Instance State EC2 instance status checks 2/2 checks passed Subnet Route Table Route to Internet Gateway (public subnet) 0.0.0.0/0 → igw-xxxxxxxx Public IP / EIP Instance has a reachable public address Public IPv4 or Elastic IP assigned Why "Connection Timed Out" Specifically? A timeout (as opposed to Connection refused ) means your TC...
Read more

IAM User vs. IAM Role: Why Your EC2 Instance Should Never Use a User

Choosing between an IAM User and an IAM Role is one of the most consequential security decisions in AWS — get it wrong and you either expose long-lived credentials or block your application entirely. This post cuts through the confusion and gives you a definitive answer for the EC2-to-S3 access pattern. TL;DR — Quick Comparison Dimension IAM User IAM Role Identity type A person or a static service account An assumable identity for AWS services, users, or external principals Credential type Long-lived Access Key ID + Secret Access Key Short-lived, auto-rotating STS tokens (max 12 h by default) Credential rotation Manual — you must rotate keys yourself Automatic — AWS rotates them transparently Stored on EC2? Yes — in ~/.aws/credentials or env vars (risky) No — delivered via the In...
Read more