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!

aws_api_gateway_account

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.

aws_api_gateway_api_key

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:

aws_api_gateway_authorizer

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.

aws_api_gateway_client_certificate

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

aws_api_gateway_deployment

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:

aws_api_gateway_documentation_part

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:

aws_api_gateway_documentation_version

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

aws_api_gateway_gateway_response

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

aws_api_gateway_integration

Defines the type of backend integration for an HTTP method:

aws_api_gateway_integration_response

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

aws_api_gateway_method

Adds an HTTP method to a resource of an API:

aws_api_gateway_method_response

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

aws_api_gateway_method_settings

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

aws_api_gateway_model

Define model schemas for your request/response body:

aws_api_gateway_request_validator

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

aws_api_gateway_resource

Add a resource to your API:

aws_api_gateway_rest_api

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

aws_api_gateway_rest_api_policy

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

aws_api_gateway_stage

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

aws_api_gateway_usage_plan

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

aws_api_gateway_usage_plan_key

This resource links your API key to your usage plan:

aws_api_gateway_vpc_link

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

Conclusion

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! 🚀

API Gateway DevOps Terraform