How can I create route path in terraform for AWS apigateway version2?

Question

I am using terraform to create API Gateway version2 on AWS. By looking at the page: https://www.terraform.io/docs/providers/aws/r/apigatewayv2_route.html, it doesn't say how to configure route path and HTTP method. I wonder where I should configure them. I can see below settings on AWS console when I create a route:

It doesn't have any of these configuration on terraform. How can I create a route with path and method?

Answer 1

The API Gateway v2 API models routes in a very generic way so that the same data models can be used for both HTTP APIs and WebSocket APIs. In both cases, it's the route_key argument that is used for matching routes.

For WebSocket APIs we can choose how API Gateway will construct a route key by setting route_selection_expression when declaring an API.

For HTTP APIs API Gateway v2 uses a single string consisting of the method followed by the path, separated by a space. For example, the following route key would match what you entered into the console for your screenshot:

  route_key = "ANY /"

The API Gateway documentation for routes offers a second example, which we can translate into Terraform like this:

  route_key = "GET /pets"

It seems like the API Gateway console is automatically combining those two fields in the UI into a single string when it creates the route.

---

A general tip for when you're trying to understand how an AWS console UI maps onto the underlying API -- and thus how it maps into Terraform -- is to create a test object in the console and then import it into Terraform to see how Terraform sees it.

In this case, you'd need to create the route with the UI as you showed, and then use the console to find the internal id of the overall API and of that route in the API Gateway API, e.g. by navigating to it in the console and looking in the browser URL bar. You can then write an empty placeholder configuration for it in Terraform and import your object into it:

resource "aws_apigatewayv2_route" "example" {
  # TODO: Fill in after import
}

terraform import aws_apigatewayv2_route.example api-id/route-id

If the import succeeds, you can then look at Terarform's understanding of the object you imported by running terraform show and looking for the resource "aws_apigatewayv2_route" "example" block in the output. You can then see the route_key that the console created and replicate it in your configuration.

It's important to be careful when using terraform import in this way, because after this Terraform believes it is the sole manager of that object and will plan to destroy it if you run terraform destroy or remove it from the configuration. For that reason, I'd suggest to do this with a temporary HTTP API created only for experimentation, not with any real existing HTTP API that you want to keep. (You can, of course, use terraform import to bring your existing API into Terraform once you've experimented enough to know how to represent the existing objects, if you do intend to use Terraform to manage the API on an ongoing basis.)