AWS API Gateway

What it is

AWS API Gateway is a fully managed service that makes it easy to create, publish, and manage APIs at any scale. It acts as the entry point between client applications and backend services, automatically handling critical tasks like authentication, authorization, throttling, caching, and monitoring.

The service eliminates the operational complexity of building and maintaining your own API infrastructure. With native integration to AWS Lambda, it enables complete serverless architectures where code runs only when needed, without managing servers.

API Gateway supports three types of APIs: REST APIs for traditional web services with full features, HTTP APIs for simple use cases with lower latency and cost, and WebSocket APIs for real-time bidirectional communication.

HTTP API vs REST API comparison

Code example: Terraform

# API Gateway HTTP API with Lambda
resource "aws_apigatewayv2_api" "main" {
  name          = "user-api"
  protocol_type = "HTTP"
  
  cors_configuration {
    allow_credentials = false
    allow_headers     = ["content-type", "x-amz-date", "authorization"]
    allow_methods     = ["GET", "POST", "PUT", "DELETE"]
    allow_origins     = ["https://app.example.com"]
    max_age          = 86400
  }
}
 
resource "aws_apigatewayv2_integration" "lambda" {
  api_id           = aws_apigatewayv2_api.main.id
  integration_type = "AWS_PROXY"
  
  connection_type      = "INTERNET"
  description         = "Lambda proxy integration"
  integration_method  = "POST"
  integration_uri     = aws_lambda_function.user_handler.invoke_arn
  passthrough_behavior = "WHEN_NO_MATCH"
}
 
resource "aws_apigatewayv2_route" "users" {
  api_id    = aws_apigatewayv2_api.main.id
  route_key = "GET /users/{id}"
  target    = "integrations/${aws_apigatewayv2_integration.lambda.id}"
  
  authorization_type = "JWT"
  authorizer_id     = aws_apigatewayv2_authorizer.jwt.id
}
 
resource "aws_apigatewayv2_stage" "prod" {
  api_id      = aws_apigatewayv2_api.main.id
  name        = "prod"
  auto_deploy = true
  
  default_route_settings {
    throttling_rate_limit  = 1000
    throttling_burst_limit = 2000
  }
}

Integration patterns

API Gateway supports multiple integration patterns depending on architectural needs:

Lambda Proxy Integration: The most common pattern for serverless architectures. API Gateway sends the entire HTTP request as a JSON event to Lambda, which must return a structured HTTP response. Ideal for complex business logic.

VPC Link to Application Load Balancer: For integrating with services running on AWS ECS or EC2 within a private VPC. API Gateway connects through a VPC Link to an internal ALB, enabling hybrid architectures.

HTTP Proxy: Forwards requests directly to external HTTP endpoints with minimal transformations. Useful for adding authentication or throttling to existing APIs.

Mock Integrations: Static responses configured directly in API Gateway, useful for testing, interactive documentation, or health check endpoints.

Authorization options

Decision: Use IAM for internal APIs, Cognito for applications with end users, JWT for integration with external providers, and Lambda Authorizer only when you need complex authorization logic.

Observability

API Gateway provides complete observability through multiple AWS services:

CloudWatch Metrics: Automatic metrics like latency, error rate, and request count per stage and method. Includes throttling and authorization failure metrics for debugging.

X-Ray Tracing: Distributed tracing that shows the complete flow from API Gateway to Lambda and other AWS services. Essential for identifying bottlenecks in complex architectures.

Access Logging: Detailed logs of each request with information like client IP, user agent, latency, and response code. Can be sent to CloudWatch Logs or S3 for later analysis.

Custom domain configuration

resource "aws_apigatewayv2_domain_name" "api" {
  domain_name = "api.example.com"
  
  domain_name_configuration {
    certificate_arn = aws_acm_certificate.api.arn
    endpoint_type   = "REGIONAL"
    security_policy = "TLS_1_2"
  }
}
 
resource "aws_apigatewayv2_api_mapping" "main" {
  api_id      = aws_apigatewayv2_api.main.id
  domain_name = aws_apigatewayv2_domain_name.api.id
  stage       = aws_apigatewayv2_stage.prod.name
}

Throttling and quotas

API Gateway implements throttling at multiple levels: account-level (10,000 RPS per region by default), stage-level, and method-level. Limits can be configured independently, and the service returns HTTP 429 when exceeded.

For applications with variable traffic, consider configuring burst limits that allow temporary spikes. Usage Plans enable creating different service levels with daily/monthly quotas for different client types.

Why it matters

API Gateway eliminates months of infrastructure development typically required to build a robust HTTP entry layer. With features like integrated authorization, automatic throttling, and native observability, it allows engineering teams to focus on business logic instead of plumbing.

The price difference between HTTP API ($1/million) and REST API ($3.50/million) can be significant at scale, but REST API offers features like caching and transformations that can reduce downstream costs. The right decision depends on traffic volume and complexity of required transformations.

References

• AWS API Gateway Documentation — AWS, 2024. Complete official documentation.
• HTTP API vs REST API Comparison — AWS, 2024. Detailed comparison between API types.
• API Gateway Pricing — AWS, 2024. Updated pricing model.
• API Gateway Quotas and Limits — AWS, 2024. Service limits and quotas.
• Best Practices for REST APIs — AWS, 2024. Best practices guide.
• API Gateway Performance Tuning — AWS Compute Blog, 2023. Performance and cost optimization.