Introduction

In AWS API Gateway, a path variable is represented by a resource whose path_part is wrapped in braces, such as {id}. In Terraform, you model that by creating a nested aws_api_gateway_resource, then wiring the method and integration so the path parameter is declared and, if needed, forwarded to the backend.

How API Gateway Models a Path Variable

Suppose you want an endpoint like:

/users/{id}

In API Gateway REST APIs, that is not one string resource. It is usually two nested resources:

• 'users'
• '{id}'

Terraform mirrors that resource tree explicitly.

Terraform Resource Structure

Here is a minimal REST API example for /users/{id}.

1resource "aws_api_gateway_rest_api" "api" {
2  name = "example-api"
3}
4
5resource "aws_api_gateway_resource" "users" {
6  rest_api_id = aws_api_gateway_rest_api.api.id
7  parent_id   = aws_api_gateway_rest_api.api.root_resource_id
8  path_part   = "users"
9}
10
11resource "aws_api_gateway_resource" "user_id" {
12  rest_api_id = aws_api_gateway_rest_api.api.id
13  parent_id   = aws_api_gateway_resource.users.id
14  path_part   = "{id}"
15}

The braces in path_part are what make it a path parameter rather than a literal segment.

Declare the Method Request Parameter

The method must explicitly declare that it expects the path parameter.

1resource "aws_api_gateway_method" "get_user" {
2  rest_api_id   = aws_api_gateway_rest_api.api.id
3  resource_id   = aws_api_gateway_resource.user_id.id
4  http_method   = "GET"
5  authorization = "NONE"
6
7  request_parameters = {
8    "method.request.path.id" = true
9  }
10}

Without that request_parameters entry, API Gateway does not know the method requires the variable path component.

Forward the Path Variable to the Backend

If your integration backend also expects the id path parameter, map it through the integration.

Example HTTP integration:

1resource "aws_api_gateway_integration" "get_user" {
2  rest_api_id = aws_api_gateway_rest_api.api.id
3  resource_id = aws_api_gateway_resource.user_id.id
4  http_method = aws_api_gateway_method.get_user.http_method
5
6  integration_http_method = "GET"
7  type                    = "HTTP"
8  uri                     = "https://example.internal/users/{id}"
9
10  request_parameters = {
11    "integration.request.path.id" = "method.request.path.id"
12  }
13}

That line is the bridge from the API Gateway path variable to the backend URL path variable.

Lambda Proxy Case

If you use Lambda proxy integration, you usually do not need to map the variable manually into a backend URL. API Gateway passes path parameters in the event payload.

Your function can read them from the event structure.

The important Terraform part is still the same: define the {id} resource and declare the method request parameter.

Deploy the API

After defining resources, create a deployment and stage.

1resource "aws_api_gateway_deployment" "main" {
2  rest_api_id = aws_api_gateway_rest_api.api.id
3
4  depends_on = [
5    aws_api_gateway_integration.get_user
6  ]
7}
8
9resource "aws_api_gateway_stage" "prod" {
10  rest_api_id   = aws_api_gateway_rest_api.api.id
11  deployment_id = aws_api_gateway_deployment.main.id
12  stage_name    = "prod"
13}

Then the route becomes something like:

.../prod/users/123

Multiple Path Variables

The same pattern scales to deeper routes such as /teams/{team_id}/users/{user_id}. Each variable path segment becomes its own nested aws_api_gateway_resource with braces in path_part.

That nesting feels verbose at first, but it matches how API Gateway actually stores route structure.

Common Pitfalls

The most common mistake is trying to set the whole route string in one resource instead of building nested API Gateway resources. Another is forgetting request_parameters on the method, which causes the path variable not to be recognized properly. Teams also often forget the integration-side path mapping for non-proxy backends and then wonder why the backend receives a literal {id} or no value at all. Finally, missing depends_on for deployment can create confusing situations where the route exists in Terraform code but is not fully deployed yet.

Summary

• In Terraform, a path variable is represented by a resource with path_part = "{id}".
• Build variable routes as nested aws_api_gateway_resource objects.
• Declare the path parameter in aws_api_gateway_method.request_parameters.
• For non-proxy integrations, map method path parameters into integration path parameters.
• Deploy the API after the method and integration are fully defined.