API Gateway serves as the front door for serverless applications on AWS. It handles routing, throttling, authentication, and more - all without you managing a single server. But configuring it through the console is tedious and error-prone. There are so many interconnected pieces that clicking through them manually just doesn't scale.
Terraform solves this by letting you define your entire API as code. In practice, this means repeatable, version-controlled API infrastructure that can be applied consistently across environments. The approach offers automatic documentation, version control for API changes, and seamless integration with AWS API Gateway.
The Terraform workflow for API Gateway typically involves defining the REST API or HTTP API resource, creating methods and integrations, deploying the API, and creating stages. Once Terraform creates the function, invoke it using the AWS CLI to verify behavior. API Gateway is an AWS managed service that allows you to create and manage HTTP or WebSocket APIs.
REST API vs HTTP API in Terraform
AWS offers two types of API Gateway: REST API v1 and HTTP API v2.
The choice drives the resource types used in Terraform.
| Feature | REST API | HTTP API |
|---|---|---|
| Feature set | More features | Simpler |
| Capabilities | request/response transformations, WAF integration, caching, API keys | Core HTTP routing |
| Cost | Higher | Cheaper |
| Performance | Standard | Faster |
REST API has more features including request/response transformations, WAF integration, caching, API keys. HTTP API is cheaper, faster, and simpler.
For new projects, use HTTP API for new projects unless you specifically need REST API features. And always set up proper logging and throttling before going to production.
The architecture for a production-ready Terraform project that deploys AWS API Gateway using OpenAPI specifications can be described in three main layers.
- OpenAPI Specification Layer
- Infrastructure Module
- Environment Configuration
OpenAPI Specification Layer: A YAML file containing all API route definitions, HTTP methods, request/response schemas, and AWS-specific integration extensions. This file serves as both the API definition and documentation source.
Infrastructure Module: Reusable Terraform code that creates the API Gateway REST API, deployment, and stage resources. The module imports the OpenAPI specification and configures automatic redeployment using SHA1 hash triggers.
Environment Configuration: Environment-specific settings for dev, staging, production that reference the infrastructure module with appropriate parameters.
OpenAPI-Driven Deployment with Terraform
This approach offers automatic documentation, version control for API changes, and seamless integration with AWS API Gateway.
The solution includes automatic redeployment triggers when API definitions change, multi-environment support, and proper state management.
State management is typically handled with S3 backend configuration.
Edit backend.hcl with your S3 bucket details:
bucket = "<your-terraform-state-bucket>"
key = "api-gateway-openapi/dev/terraform.tfstate"
region = "us-east-1"
Initialize Terraform with the backend configuration:
terraform init -backend-config=backend.hcl
This command downloads the AWS provider, configures the S3 backend for state storage, and initializes the infrastructure module.
Review the execution plan:
terraform plan -out=tfplan
Expected output shows resources to be created:
```
Terraform will perform the following actions:
module.apigateway.awsapigatewaydeployment.deploy will be created
module.apigateway.awsapigatewayrest_api.api will be created
module.apigateway.awsapigatewaystage.stage will be created
Plan: 3 to add, 0 to change, 0 to destroy.
```
Deploy the infrastructure:
terraform apply "tfplan"
After successful deployment, Terraform displays the API endpoint.
Outputs:
api_url = "https://abc123def4.execute-api.us-east-1.amazonaws.com/dev"
Retrieve the API URL:
terraform output api_url
Test the endpoints:
curl https://<api-id>.execute-api.us-east-1.amazonaws.com/dev/users
Expected response:
{
"message": "GET /users - Request received successfully",
"users": ["user1", "user2"]
}
Test the GET /products endpoint:
curl https://<api-id>.execute-api.us-east-1.amazonaws.com/dev/products
Apply changes to the OpenAPI file and reapply:
terraform apply
The API automatically redeploys with the updated OpenAPI specification.
Resource actions are indicated with the following symbols:
```
+ create
Terraform will perform the following actions:
awsapigatewaydeployment.cruddeployment will be created
- resource "awsapigatewaydeployment" "cruddeployment" {
- created_date = (known after apply)
- execution_arn = (known after apply)
- id = (known after apply)
- invoke_url = (known after apply)
- restapiid = (known after apply)
}
```
One for each of the resources we are going to deploy.
Method Settings, Throttling and Stage Configuration
Without proper controls, a single client can overwhelm your backend.
Throttle settings for the stage can be applied with awsapigatewaymethodsettings:
resource "aws_api_gateway_method_settings" "all" {
rest_api_id = aws_api_gateway_rest_api.my_api.id
stage_name = aws_api_gateway_stage.prod.stage_name
method_path = "*/*"
settings {
throttling_burst_limit = 100
throttling_rate_limit = 50
metrics_enabled = true
logging_level = "INFO"
}
}
This configuration sets throttlingburstlimit to 100 and throttlingratelimit to 50, enables metrics, and sets logging_level to INFO for all methods in the stage.
Implement Throttling and Quotas with usage plans to control API access:
resource "aws_api_gateway_usage_plan" "plan" {
name = "${var.project_name}-${var.environment}-plan"
api_stages {
api_id = aws_api_gateway_rest_api.api.id
stage = aws_api_gateway_stage.stage.stage_name
}
throttle_settings {
burst_limit = 100
rate_limit = 50
}
quota_settings {
limit = 10000
period = "DAY"
}
}
Reference: API Gateway throttling and quotas.
Wrapping up, API Gateway with Terraform can feel verbose, especially the REST API variant. But once you have it working, you've got a repeatable, version-controlled API infrastructure.
Logging, Monitoring and Best Practices
Enable CloudWatch Logging by adding logging configuration to the stage resource:
resource "aws_api_gateway_stage" "stage" {
stage_name = var.environment
rest_api_id = aws_api_gateway_rest_api.api.id
deployment_id = aws_api_gateway_deployment.deploy.id
access_log_settings {
destination_arn = aws_cloudwatch_log_group.api_logs.arn
format = jsonencode({
requestId = "$context.requestId"
ip = "$context.identity.sourceIp"
requestTime = "$context.requestTime"
httpMethod = "$context.httpMethod"
resourcePath = "$context.resourcePath"
status = "$context.status"
protocol = "$context.protocol"
responseLength = "$context.responseLength"
})
}
}
resource "aws_cloudwatch_log_group" "api_logs" {
name = "/aws/apigateway/${var.project_name}-${var.environment}"
retention_in_days = 7
}
Learn more about API Gateway logging.
Monitoring and best practices include:
- Enable CloudWatch Logging
- Implement Throttling and Quotas
- Use Custom Domain Names: Configure custom domain names with SSL certificates for production
Security Recommendations include using custom domain names with SSL certificates for production.
The Terraform apply process for a Lambda integration example shows:
Respond to the confirmation prompt with a yes
```
$ terraform apply
...
Apply complete! Resources: 4 added, 0 changed, 0 destroyed.
Outputs:
functionname = "HelloWorld"
lambdabucket_name = "learn-terraform-functions-formally-cheaply-frank-mullet"
```
Once Terraform creates the function, invoke it using the AWS CLI.
$ aws lambda invoke --region=us-east-1 --function-name=$(terraform output -raw function_name) response.json
{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
Check the contents of response.json to confirm that the function is working as expected.
$ cat response.json
{"statusCode":200,"headers":{"Content-Type":"application/json"},"body":"{\"message\":\"Hello, World!\"}"}
This response matches the object returned by the handler function in hello-world/hello.js
You can review your function in the AWS Lambda Console.
Conclusion
Terraform-based API Gateway deployments shift API infrastructure from manual console clicks to declarative code. The method settings resource allows centralized control of throttling, metrics, and logging per stage, preventing a single client from overwhelming backend services. Pairing this with usage plans that enforce burstlimit, ratelimit, and daily quotas provides a production-ready guardrail.
OpenAPI-driven workflows reduce drift between documentation and implementation and enable automatic redeployment when the specification changes. Using S3 backend configuration for state, initializing with terraform init -backend-config=backend.hcl, planning with terraform plan -out=tfplan, and applying with terraform apply creates a repeatable pipeline across dev, staging, and production.
REST API remains the choice when advanced features such as request/response transformations, WAF integration, caching, and API keys are required. HTTP API delivers lower cost and higher speed for straightforward HTTP workloads. In both cases, enabling CloudWatch access logs with structured JSON formats and setting retention policies ensures observability, while custom domains with SSL provide secure production endpoints.
The verbosity of REST API definitions in Terraform is offset by version control, peer review, and consistent multi-environment promotion. Keeping throttling, logging, and monitoring configured from the first deployment avoids retrofitting production APIs under load.