API Gateway

The Core Concept of a REST API

At its simplest, API Gateway acts as a reverse proxy for your backend resources, such as Lambda functions or EC2 instances. When a client sends an HTTP request, the gateway intercepts it before it ever reaches your application code. This is fundamental because it decouples the client's interface from your backend implementation. By defining Resources and Methods, you create a mapping layer. Why does this matter? If you move from a monolithic backend to a microservices architecture, you can update the API Gateway routing rules without forcing the client to change their endpoint URL. The gateway handles the heavy lifting of mapping URL parameters and query strings to the format your backend expects, ensuring your application logic remains clean and focused solely on processing the business request rather than parsing headers or managing connection pooling at the edge.

# Example of a CLI command to create an API REST resource structure
aws apigateway create-resource --rest-api-id <api-id> --parent-id <parent-id> --path-part "orders" # Creates the /orders endpoint

Integration Types and Request Mapping

API Gateway offers two primary integration types: Proxy Integration and Non-Proxy Integration. In Proxy Integration, the entire HTTP request—including headers, query parameters, and the body—is passed directly to your backend, like a Lambda function, in a structured format. This is the preferred method for most modern serverless architectures because it places the control inside your application code. In contrast, Non-Proxy Integration requires you to define a Mapping Template using a template language to transform the incoming request body into a specific format expected by your backend. You would choose Non-Proxy Integration when you need to enforce strict schema validation at the gateway level or when you want to transform a legacy backend response into a standardized JSON format before returning it to the user. This transformation capability allows you to maintain consistent API contracts even if your underlying backend services are inconsistent.

# Mapping template example for a VTL request integration (non-proxy)
# Set input.json to match backend requirements
{"orderId": "$input.params('orderId')", "status": "pending"}

Security and Authentication Mechanisms

Security is a core pillar of API Gateway. Because the gateway serves as the first point of contact, it is the ideal place to implement authentication and authorization. You can integrate it with Lambda Authorizers, which allow you to run custom authentication logic for every request. This is critical for scenarios like verifying JSON Web Tokens (JWT) or checking headers against an external database. Additionally, you can utilize Amazon Cognito User Pools for managed authentication, ensuring that only users with valid tokens can reach your backend. By offloading these security checks to the gateway, you prevent unauthorized requests from triggering your backend services, which effectively protects your application from compute costs and potential denial-of-service attacks. This architectural pattern ensures that your business logic remains isolated from the mechanics of identity verification, creating a robust perimeter around your microservices.

# Terraform snippet for adding an authorizer to a method
resource "aws_api_gateway_authorizer" "auth" {
  name = "jwt-authorizer"
  rest_api_id = aws_api_gateway_rest_api.api.id
  authorizer_uri = aws_lambda_function.auth_func.invoke_arn
}

Throttling and Usage Plans

To maintain system stability, you must control the rate at which requests are processed. API Gateway provides built-in throttling and usage plans that allow you to define rate limits and burst limits per client. This is essential for protecting your downstream services from unexpected traffic spikes that could lead to resource exhaustion or increased costs. A rate limit defines the steady-state number of requests per second, while a burst limit handles short-term surges. Beyond basic throttling, Usage Plans allow you to associate specific API keys with clients, providing tiered access levels. For instance, you could offer a free tier with limited requests per day and a paid tier with higher limits. This mechanism not only safeguards your infrastructure but also provides a monetization pathway for your APIs, as you can track usage precisely and ensure fair distribution of system capacity among your various consumers.

# CLI command to set a usage plan limit
aws apigateway create-usage-plan --name "GoldPlan" --throttle "{\"burstLimit\": 200, \"rateLimit\": 100}"

Stages and Deployment Management

Deployments in API Gateway are managed through Stages, which represent a snapshot of your API configuration. A stage could be 'dev', 'staging', or 'prod'. By separating these environments, you can test changes in isolation without impacting live users. When you update your resources or methods, those changes are not live until you redeploy the API to a stage. This promotes a disciplined development workflow where you can perform canary releases. A canary release allows you to route a small percentage of traffic to a new version of your API, enabling you to monitor performance and error rates before rolling out the update to the entire user base. Because the gateway handles the routing of traffic between these versions, you achieve seamless updates that minimize downtime and mitigate the risk associated with introducing breaking changes in a high-traffic production environment.

# CLI command to create a deployment stage for production
aws apigateway create-deployment --rest-api-id <api-id> --stage-name "prod"

Interview questions

All AWS interview questions →

Check yourself

Take the full AWS quiz →