How to Create API Gateway with Terraform: Simple Guide

To create an AWS API Gateway using Terraform, define a aws_api_gateway_rest_api resource for the API, then add resources and methods like aws_api_gateway_resource and aws_api_gateway_method. Finally, deploy the API with aws_api_gateway_deployment to make it live.

Syntax

This is the basic syntax to create an API Gateway REST API in Terraform:

• aws_api_gateway_rest_api: Defines the API itself.
• aws_api_gateway_resource: Creates a path under the API.
• aws_api_gateway_method: Defines HTTP methods like GET or POST on the resource.
• aws_api_gateway_integration: Connects the method to backend services.
• aws_api_gateway_deployment: Deploys the API to a stage.

terraform

resource "aws_api_gateway_rest_api" "example" {
  name        = "example-api"
  description = "Example API Gateway"
}

resource "aws_api_gateway_resource" "example_resource" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  parent_id   = aws_api_gateway_rest_api.example.root_resource_id
  path_part   = "example"
}

resource "aws_api_gateway_method" "example_method" {
  rest_api_id   = aws_api_gateway_rest_api.example.id
  resource_id   = aws_api_gateway_resource.example_resource.id
  http_method   = "GET"
  authorization = "NONE"
}

resource "aws_api_gateway_integration" "example_integration" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  resource_id = aws_api_gateway_resource.example_resource.id
  http_method = aws_api_gateway_method.example_method.http_method

  integration_http_method = "GET"
  type                    = "MOCK"
}

resource "aws_api_gateway_deployment" "example_deployment" {
  depends_on = [aws_api_gateway_method.example_method]
  rest_api_id = aws_api_gateway_rest_api.example.id
  stage_name  = "prod"
}

Example

This example creates a simple API Gateway with a GET method on the path /example. It uses a MOCK integration that returns a default response. The API is deployed to the prod stage.

terraform

provider "aws" {
  region = "us-east-1"
}

resource "aws_api_gateway_rest_api" "example" {
  name        = "example-api"
  description = "Example API Gateway"
}

resource "aws_api_gateway_resource" "example_resource" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  parent_id   = aws_api_gateway_rest_api.example.root_resource_id
  path_part   = "example"
}

resource "aws_api_gateway_method" "example_method" {
  rest_api_id   = aws_api_gateway_rest_api.example.id
  resource_id   = aws_api_gateway_resource.example_resource.id
  http_method   = "GET"
  authorization = "NONE"
}

resource "aws_api_gateway_integration" "example_integration" {
  rest_api_id             = aws_api_gateway_rest_api.example.id
  resource_id             = aws_api_gateway_resource.example_resource.id
  http_method             = aws_api_gateway_method.example_method.http_method
  integration_http_method = "GET"
  type                    = "MOCK"
}

resource "aws_api_gateway_deployment" "example_deployment" {
  depends_on = [aws_api_gateway_method.example_method]
  rest_api_id = aws_api_gateway_rest_api.example.id
  stage_name  = "prod"
}

Output

Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

Common Pitfalls

Common mistakes when creating API Gateway with Terraform include:

• Not setting depends_on for deployment, causing deployment before integration is ready.
• Forgetting to specify authorization or setting it incorrectly.
• Missing integration_http_method in aws_api_gateway_integration.
• Not deploying the API after changes, so updates don't appear.

terraform

/* Wrong: Missing depends_on causes deployment to fail or deploy empty API */
resource "aws_api_gateway_deployment" "wrong_deployment" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  stage_name  = "prod"
}

/* Right: depends_on ensures integration is ready before deployment */
resource "aws_api_gateway_deployment" "correct_deployment" {
  depends_on = [aws_api_gateway_method.example_method]
  rest_api_id = aws_api_gateway_rest_api.example.id
  stage_name  = "prod"
}

Quick Reference

Remember these key points when creating API Gateway with Terraform:

• Define API: Use aws_api_gateway_rest_api.
• Add resources: Use aws_api_gateway_resource for paths.
• Set methods: Use aws_api_gateway_method for HTTP verbs.
• Integrate backend: Use aws_api_gateway_integration.
• Deploy API: Use aws_api_gateway_deployment with depends_on.

Key Takeaways

Always define the API, resources, methods, integrations, and deployment in Terraform.

Use depends_on in deployment to ensure all integrations are ready before deploying.

Set authorization explicitly to avoid access issues.

Deploy the API after changes to make them live.

Use MOCK integration for simple testing without backend.