Understanding the Terraform Resources that Create an AWS API Gateway REST API

If you have ever tried to create a REST API in AWS API Gateway using Terraform, you know how cumbersome it can be. There is no decent Terraform module for the REST API that can abstract away the details or at least combine them into a single resource for ease of use. As a result, we are forced to use the “raw” resources provided by the AWS Terraform provider, and there are TWENTY FOUR of those!

If you are a visual learner like me, it would really help if you could map those resources onto the API Gateway UI. “Seeing” which resource creates what would make it really easy to pick the right ones for your use case and give them just the right arguments to get your desired outcome.

In this article, I will do just that: map the resources to the UI. Let’s get started!


The first resource we will look at is aws_api_gateway_account. It provides a way to specify settings for the API Gateway service per AWS account. Currently, it only supports one argument: cloudwatch_role_arn, which specifies the IAM role that API Gateway will assume to talk to other AWS services. For example, consider a role to allow CloudWatch access:

Note that cloudwatch_role_arn is optional, so you can create an empty aws_api_gateway_account resource if you are interested in its outputs, which returns the API throttle settings for your account. That includes the rate limit and the burst limit for the total number of API requests per second.

For more details about this resource, see its official Terraform documentation here.


This one is pretty self-explanatory. It’s the API key you give out to the consumers of your API to track (and limit) their usage:


This is the authorizer used to authenticate and authorize incoming requests to your APIs. It could be one of IAM, a Cognito user pool, or a Lambda function:

Custom Domain

The next two resources together set up a custom domain for your API:

  • aws_api_gateway_domain_name defines the domain like api.example.com.
  • aws_api_gateway_base_path_mapping maps a sub-path of your domain URL to a stage of your API.


Client certificates are used to verify that the requests reaching your backend did indeed come from API Gateway:


After you have defined the resources (endpoints) and (HTTP) methods of your API, you deploy it to a stage. The “deployment” from definition to stage is captured by this resource:


This is how you add documentation for the individual pieces of your API, like the supported HTTP methods for a path, query and path parameters, request and response body and headers, etc. For example, each of the boxes you see below is a documentation part:


When you publish documentation for a stage, you create a documentation version:


API Gateway provides many predefined standard responses to requests. You can add more using this resource.


Defines the type of backend integration for an HTTP method:


Map backend responses to API responses here, using VTL if required:


Adds an HTTP method to a resource of an API:


Defines an HTTP method’s response status code, headers, and body:


Use this resource to set CloudWatch and throttling settings per method in a stage:


Define model schemas for your request/response body:


Define which parts of the incoming request should be validated by API Gateway:


Add a resource to your API:


The parent resource of all API resources and their HTTP methods:


The IAM policy that controls access to who can invoke these APIs:


Your API must be deployed to a stage before it can be invoked:


A usage plan limits how many requests your API consumers can make:


This resource links your API key to your usage plan:

Links your API to a Network Load Balancer in a VPC:


Phew! That’s all of it. We have looked at every one of the twenty-four Terraform resources used to create a REST API in AWS API Gateway. Hopefully, now you have a better understanding of what each resource does. Happy Terraforming!

About the Author ✍🏻

Harish KM is a Principal DevOps Engineer at QloudX & a top-ranked AWS Ambassador since 2020. 👨🏻‍💻

With over a decade of industry experience as everything from a full-stack engineer to a cloud architect, Harish has built many world-class solutions for clients around the world! 👷🏻‍♂️

With over 20 certifications in cloud (AWS, Azure, GCP), containers (Kubernetes, Docker) & DevOps (Terraform, Ansible, Jenkins), Harish is an expert in a multitude of technologies. 📚

These days, his focus is on the fascinating world of DevOps & how it can transform the way we do things! 🚀

One Reply to “Understanding the Terraform Resources that Create an AWS API Gateway REST API”

  1. Josh says:

    Great help

Leave a Reply

Your email address will not be published. Required fields are marked *