AWS API Gateway — Managed Gateway for Serverless and REST APIs

In this tutorial, you will learn about AWS API Gateway. We cover key concepts, practical examples, and best practices to help you master this topic.

AWS API Gateway is a fully managed service for creating, deploying, and scaling APIs that integrates with Lambda, DynamoDB, and other AWS services, handling authentication, throttling, and monitoring automatically.

What You'll Learn

• REST API vs. HTTP API vs. Websocket API in AWS Gateway
• Integrating API Gateway with Lambda and DynamoDB
• Usage plans, API keys, and throttling

Why It Matters

Managing gateway infrastructure yourself requires provisioning servers, configuring Nginx/Kong, and handling scaling. AWS API Gateway eliminates server management, scales automatically, and integrates natively with AWS services like Lambda and CloudWatch.

Real-World Use

Durga Antivirus Pro's scan submission endpoint runs on AWS API Gateway with a Lambda backend. The gateway handles authentication via Cognito, throttles at 1000 requests per second, logs to CloudWatch, and caches scan results for 5 minutes. The team manages zero infrastructure.

flowchart LR
    Client["Client"] --> APIGW["API Gateway"]
    APIGW --> Lambda["Lambda\nFunction"]
    Lambda --> DynamoDB["DynamoDB"]
    APIGW --> Cognito["Cognito\nAuth"]
    APIGW --> CloudWatch["CloudWatch\nLogs & Metrics"]
    style APIGW fill:#dbeafe,stroke:#2563eb

Creating a REST API with Lambda Integration

Using the AWS CLI:

# Create the API
API_ID=$(aws apigateway create-rest-api \
  --name "DurgaScanAPI" \
  --description "Scan submission API" \
  --query "id" \
  --output text)

# Get the root resource ID
ROOT_ID=$(aws apigateway get-resources \
  --rest-api-id $API_ID \
  --query "items[0].id" \
  --output text)

# Create a /scan resource
RESOURCE_ID=$(aws apigateway create-resource \
  --rest-api-id $API_ID \
  --parent-id $ROOT_ID \
  --path-part "scan" \
  --query "id" \
  --output text)

# Set up POST method with Lambda proxy
aws apigateway put-method \
  --rest-api-id $API_ID \
  --resource-id $RESOURCE_ID \
  --http-method POST \
  --authorization-type NONE

aws apigateway put-integration \
  --rest-api-id $API_ID \
  --resource-id $RESOURCE_ID \
  --http-method POST \
  --type AWS_PROXY \
  --integration-http-method POST \
  --uri "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:scan-handler/invocations"

Lambda Handler for the Gateway

import json
import boto3

dynamodb = boto3.resource("dynamodb")
table = dynamodb.Table("scans")

def lambda_handler(event, context):
    body = json.loads(event.get("body", "{}"))
    scan_id = body.get("scan_id")

    if not scan_id:
        return {
            "statusCode": 400,
            "body": json.dumps({"error": "scan_id is required"})
        }

    table.put_item(Item={"scan_id": scan_id, "status": "queued"})

    return {
        "statusCode": 200,
        "body": json.dumps({
            "scan_id": scan_id,
            "status": "queued",
            "message": "Scan submitted"
        })
    }

Usage Plans and API Keys

# Create a usage plan with throttling
aws apigateway create-usage-plan \
  --name "PartnerPlan" \
  --description "100 req/sec with burst of 200" \
  --throttle burstLimit=200,rateLimit=100 \
  --quota limit=100000,period=MONTH

# Create an API key
aws apigateway create-api-key \
  --name "Partner1Key" \
  --enabled \
  --value "sk-live-partner-key-123"

# Associate key with plan
aws apigateway create-usage-plan-key \
  --usage-plan-id "plan-id" \
  --key-type "API_KEY" \
  --key-id "key-id"

Common Mistakes

1. Exposing Lambda Errors Directly

Lambda errors return 502 with cryptic messages. Use Gateway response customization or catch exceptions in Lambda to return proper HTTP responses.

2. Not Enabling CloudWatch Logs

Without logging, debugging failures is nearly impossible. Enable full request/response logging during development.

3. CORS Configuration Issues

Browser-based clients need CORS headers. Enable CORS on the Gateway resource and ensure the Lambda returns the correct Access-Control-Allow-Origin header.

4. 29-Second Lambda Timeout

API Gateway has a 29-second timeout for Lambda integrations. If your Lambda takes longer, use async invocation or step functions.

5. Cold Starts on Critical Paths

Lambda cold starts add 200ms-1s latency. Use provisioned concurrency for latency-sensitive endpoints.

Practice Questions

1. What are the three types of APIs offered by AWS API Gateway?
2. How does AWS API Gateway integrate with Lambda?
3. What is a usage plan and how does it enforce rate limits?
4. Why does API Gateway timeout at 29 seconds for Lambda?
5. How can you reduce cold start latency for critical endpoints?

Answers:

1. REST API (full-featured, request/response transformation), HTTP API (cheaper, simpler), WebSocket API (real-time bidirectional).
2. The Gateway invokes Lambda via AWS_PROXY integration, passing the entire HTTP request as an event and returning the Lambda response as HTTP.
3. A usage plan defines throttle (rate/burst limits) and quota (monthly request cap) and associates with API keys for client differentiation.
4. API Gateway has a hard 29-second integration timeout. This is a service limit that cannot be increased.
5. Use provisioned concurrency to keep Lambda functions warm and eliminate cold starts.

Challenge: Create an AWS API Gateway REST API with a Lambda backend for a product catalog. Implement GET (list products), POST (add product), and DELETE (remove product) methods. Add a usage plan with 50 req/sec throttle and associate an API key.

FAQ

Mini Project

Create an AWS API Gateway REST API with a DynamoDB-backed Lambda for a simple task list. Implement CRUD operations, enable CORS, set up CloudWatch logging, and create a usage plan with API key authentication.

What's Next

Continue with Nginx as API Gateway for a lightweight high-performance gateway, or explore Envoy Proxy Gateway for service mesh integration.