How to build a REST API with Amazon API Gateway

Amazon API Gateway is a managed front door for APIs. It handles routing, authentication, throttling, and request validation, forwarding traffic to Lambda functions or HTTP backends. It comes in two flavors: HTTP APIs (cheaper, faster, fewer features) and REST APIs (richer, with request validation and usage plans).

Prerequisites

• An AWS account and Terraform.
• A backend to integrate, a Lambda function or an HTTP endpoint.

Steps

1. Choose an API type

For most modern workloads, pick the HTTP API. Choose the REST API only when you need API keys with usage plans, request/response transformations, or WAF integration on the REST type.

2. Define routes

resource "aws_apigatewayv2_route" "get_items" {
  api_id    = aws_apigatewayv2_api.http.id
  route_key = "GET /items"
  target    = "integrations/${aws_apigatewayv2_integration.items.id}"
}

Route keys combine an HTTP method and path.

3. Integrate the backend

Use an AWS_PROXY integration for Lambda or HTTP_PROXY for an existing service. Proxy integrations pass the request through unchanged.

4. Add an authorizer

For token-based auth, attach a JWT authorizer pointing at your identity provider:

resource "aws_apigatewayv2_authorizer" "jwt" {
  api_id           = aws_apigatewayv2_api.http.id
  authorizer_type  = "JWT"
  identity_sources = ["$request.header.Authorization"]
  jwt_configuration {
    audience = ["my-api"]
    issuer   = "https://issuer.example.com"
  }
}

5. Configure a stage

A stage is a deployable snapshot, often prod. Enable auto-deploy so route changes go live, and turn on access logging to CloudWatch.

6. Enable throttling

Set default route throttling to protect the backend:

default_route_settings {
  throttling_burst_limit = 100
  throttling_rate_limit  = 50
}

Verification

Call a protected route without a token and confirm a 401, then call with a valid token and confirm a 200. Inspect CloudWatch access logs for status codes and latency. Exceed the rate limit and confirm 429 responses.

Next Steps

Add a custom domain with ACM, validate request bodies with models, and create usage plans with API keys if you need per-client quotas.