Manages an API Gateway REST API. The REST API can be configured via importing an OpenAPI specification in the body
argument (with other arguments serving as overrides) or via other Terraform resources to manage the resources (aws_api_gateway_resource
resource), methods (aws_api_gateway_method
resource), integrations (aws_api_gateway_integration
resource), etc. of the REST API. Once the REST API is configured, the aws_api_gateway_deployment
resource can be used along with the aws_api_gateway_stage
resource to publish the REST API.
An end-to-end example of a REST API configured with OpenAPI can be found in the /examples/api-gateway-rest-api-openapi
directory within the GitHub repository.
resource "aws_api_gateway_rest_api" "example" {
body = jsonencode({
openapi = "3.0.1"
info = {
title = "example"
version = "1.0"
}
paths = {
"/path1" = {
get = {
x-amazon-apigateway-integration = {
httpMethod = "GET"
payloadFormatVersion = "1.0"
type = "HTTP_PROXY"
uri = "https://ip-ranges.amazonaws.com/ip-ranges.json"
}
}
}
}
})
name = "example"
endpoint_configuration {
types = ["REGIONAL"]
}
}
resource "aws_api_gateway_deployment" "example" {
rest_api_id = aws_api_gateway_rest_api.example.id
triggers = {
redeployment = sha1(jsonencode(aws_api_gateway_rest_api.example.body))
}
lifecycle {
create_before_destroy = true
}
}
resource "aws_api_gateway_stage" "example" {
deployment_id = aws_api_gateway_deployment.example.id
rest_api_id = aws_api_gateway_rest_api.example.id
stage_name = "example"
}
Using put_rest_api_mode
= merge
when importing the OpenAPI Specification, the AWS control plane will not delete all existing literal properties that are not explicitly set in the OpenAPI definition. Impacted API Gateway properties: ApiKeySourceType, BinaryMediaTypes, Description, EndpointConfiguration, MinimumCompressionSize, Name, Policy).
data "aws_availability_zones" "available" {
state = "available"
filter {
name = "opt-in-status"
values = ["opt-in-not-required"]
}
}
data "aws_region" "current" {}
resource "aws_vpc" "example" {
cidr_block = "10.0.0.0/16"
enable_dns_support = true
enable_dns_hostnames = true
}
resource "aws_default_security_group" "example" {
vpc_id = aws_vpc.example.id
}
resource "aws_subnet" "example" {
availability_zone = data.aws_availability_zones.available.names[0]
cidr_block = cidrsubnet(aws_vpc.example.cidr_block, 8, 0)
vpc_id = aws_vpc.example.id
}
resource "aws_vpc_endpoint" "example" {
count = 3
private_dns_enabled = false
security_group_ids = [aws_default_security_group.example.id]
service_name = "com.amazonaws.${data.aws_region.current.name}.execute-api"
subnet_ids = [aws_subnet.example.id]
vpc_endpoint_type = "Interface"
vpc_id = aws_vpc.example.id
}
resource "aws_api_gateway_rest_api" "example" {
body = jsonencode({
openapi = "3.0.1"
info = {
title = "example"
version = "1.0"
}
paths = {
"/path1" = {
get = {
x-amazon-apigateway-integration = {
httpMethod = "GET"
payloadFormatVersion = "1.0"
type = "HTTP_PROXY"
uri = "https://ip-ranges.amazonaws.com/ip-ranges.json"
}
}
}
}
})
name = "example"
put_rest_api_mode = "merge"
endpoint_configuration {
types = ["PRIVATE"]
vpc_endpoint_ids = [aws_vpc_endpoint.example[0].id, aws_vpc_endpoint.example[1].id, aws_vpc_endpoint.example[2].id]
}
}
resource "aws_api_gateway_deployment" "example" {
rest_api_id = aws_api_gateway_rest_api.example.id
triggers = {
redeployment = sha1(jsonencode(aws_api_gateway_rest_api.example.body))
}
lifecycle {
create_before_destroy = true
}
}
resource "aws_api_gateway_stage" "example" {
deployment_id = aws_api_gateway_deployment.example.id
rest_api_id = aws_api_gateway_rest_api.example.id
stage_name = "example"
}
resource "aws_api_gateway_rest_api" "example" {
name = "example"
}
resource "aws_api_gateway_resource" "example" {
parent_id = aws_api_gateway_rest_api.example.root_resource_id
path_part = "example"
rest_api_id = aws_api_gateway_rest_api.example.id
}
resource "aws_api_gateway_method" "example" {
authorization = "NONE"
http_method = "GET"
resource_id = aws_api_gateway_resource.example.id
rest_api_id = aws_api_gateway_rest_api.example.id
}
resource "aws_api_gateway_integration" "example" {
http_method = aws_api_gateway_method.example.http_method
resource_id = aws_api_gateway_resource.example.id
rest_api_id = aws_api_gateway_rest_api.example.id
type = "MOCK"
}
resource "aws_api_gateway_deployment" "example" {
rest_api_id = aws_api_gateway_rest_api.example.id
triggers = {
# NOTE: The configuration below will satisfy ordering considerations,
# but not pick up all future REST API changes. More advanced patterns
# are possible, such as using the filesha1() function against the
# Terraform configuration file(s) or removing the .id references to
# calculate a hash against whole resources. Be aware that using whole
# resources will show a difference after the initial implementation.
# It will stabilize to only change when resources change afterwards.
redeployment = sha1(jsonencode([
aws_api_gateway_resource.example.id,
aws_api_gateway_method.example.id,
aws_api_gateway_integration.example.id,
]))
}
lifecycle {
create_before_destroy = true
}
}
resource "aws_api_gateway_stage" "example" {
deployment_id = aws_api_gateway_deployment.example.id
rest_api_id = aws_api_gateway_rest_api.example.id
stage_name = "example"
}
This resource supports the following arguments:
api_key_source
- (Optional) Source of the API key for requests. Valid values are HEADER
(default) and AUTHORIZER
. If importing an OpenAPI specification via the body
argument, this corresponds to the x-amazon-apigateway-api-key-source
extension. If the argument value is provided and is different than the OpenAPI value, the argument value will override the OpenAPI value.binary_media_types
- (Optional) List of binary media types supported by the REST API. By default, the REST API supports only UTF-8-encoded text payloads. If importing an OpenAPI specification via the body
argument, this corresponds to the x-amazon-apigateway-binary-media-types
extension. If the argument value is provided and is different than the OpenAPI value, the argument value will override the OpenAPI value.body
- (Optional) OpenAPI specification that defines the set of routes and integrations to create as part of the REST API. This configuration, and any updates to it, will replace all REST API configuration except values overridden in this resource configuration and other resource updates applied after this resource but before any aws_api_gateway_deployment
creation. More information about REST API OpenAPI support can be found in the API Gateway Developer Guide.description
- (Optional) Description of the REST API. If importing an OpenAPI specification via the body
argument, this corresponds to the info.description
field. If the argument value is provided and is different than the OpenAPI value, the argument value will override the OpenAPI value.disable_execute_api_endpoint
- (Optional) Whether clients can invoke your API by using the default execute-api endpoint. By default, clients can invoke your API with the default https://{api_id}.execute-api.{region}.amazonaws.com endpoint. To require that clients use a custom domain name to invoke your API, disable the default endpoint. Defaults to false
. If importing an OpenAPI specification via the body
argument, this corresponds to the x-amazon-apigateway-endpoint-configuration
extension disableExecuteApiEndpoint
property. If the argument value is true
and is different than the OpenAPI value, the argument value will override the OpenAPI value.endpoint_configuration
- (Optional) Configuration block defining API endpoint configuration including endpoint type. Defined below.minimum_compression_size
- (Optional) Minimum response size to compress for the REST API. String containing an integer value between -1
and 10485760
(10MB). -1
will disable an existing compression configuration, and all other values will enable compression with the configured size. New resources can simply omit this argument to disable compression, rather than setting the value to -1
. If importing an OpenAPI specification via the body
argument, this corresponds to the x-amazon-apigateway-minimum-compression-size
extension. If the argument value is provided and is different than the OpenAPI value, the argument value will override the OpenAPI value.name
- (Required) Name of the REST API. If importing an OpenAPI specification via the body
argument, this corresponds to the info.title
field. If the argument value is different than the OpenAPI value, the argument value will override the OpenAPI value.fail_on_warnings
- (Optional) Whether warnings while API Gateway is creating or updating the resource should return an error or not. Defaults to false
parameters
- (Optional) Map of customizations for importing the specification in the body
argument. For example, to exclude DocumentationParts from an imported API, set ignore
equal to documentation
. Additional documentation, including other parameters such as basepath
, can be found in the API Gateway Developer Guide.policy
- (Optional) JSON formatted policy document that controls access to the API Gateway. For more information about building AWS IAM policy documents with Terraform, see the AWS IAM Policy Document Guide. Terraform will only perform drift detection of its value when present in a configuration. We recommend using the aws_api_gateway_rest_api_policy
resource instead. If importing an OpenAPI specification via the body
argument, this corresponds to the x-amazon-apigateway-policy
extension. If the argument value is provided and is different than the OpenAPI value, the argument value will override the OpenAPI value.put_rest_api_mode
- (Optional) Mode of the PutRestApi operation when importing an OpenAPI specification via the body
argument (create or update operation). Valid values are merge
and overwrite
. If unspecificed, defaults to overwrite
(for backwards compatibility). This corresponds to the x-amazon-apigateway-put-integration-method
extension. If the argument value is provided and is different than the OpenAPI value, the argument value will override the OpenAPI value.tags
- (Optional) Key-value map of resource tags. If configured with a provider default_tags
configuration block present, tags with matching keys will overwrite those defined at the provider-level.Note: If the body
argument is provided, the OpenAPI specification will be used to configure the resources, methods and integrations for the Rest API. If this argument is provided, the following resources should not be managed as separate ones, as updates may cause manual resource updates to be overwritten:
aws_api_gateway_resource
aws_api_gateway_method
aws_api_gateway_method_response
aws_api_gateway_method_settings
aws_api_gateway_integration
aws_api_gateway_integration_response
aws_api_gateway_gateway_response
aws_api_gateway_model
types
- (Required) List of endpoint types. This resource currently only supports managing a single value. Valid values: EDGE
, REGIONAL
or PRIVATE
. If unspecified, defaults to EDGE
. If set to PRIVATE
recommend to set put_rest_api_mode
= merge
to not cause the endpoints and associated Route53 records to be deleted. Refer to the documentation for more information on the difference between edge-optimized and regional APIs.vpc_endpoint_ids
- (Optional) Set of VPC Endpoint identifiers. It is only supported for PRIVATE
endpoint type. If importing an OpenAPI specification via the body
argument, this corresponds to the x-amazon-apigateway-endpoint-configuration
extension vpcEndpointIds
property. If the argument value is provided and is different than the OpenAPI value, the argument value will override the OpenAPI value.This resource exports the following attributes in addition to the arguments above:
arn
- ARNcreated_date
- Creation date of the REST APIexecution_arn
- Execution ARN part to be used in lambda_permission
's source_arn
when allowing API Gateway to invoke a Lambda function,
e.g., arn:aws:execute-api:eu-west-2:123456789012:z4675bid1j
, which can be concatenated with allowed stage, method and resource path.id
- ID of the REST APIroot_resource_id
- Resource ID of the REST API's roottags_all
- Map of tags assigned to the resource, including those inherited from the provider default_tags
configuration block.In Terraform v1.5.0 and later, use an import
block to import aws_api_gateway_rest_api
using the REST API ID. For example:
import {
to = aws_api_gateway_rest_api.example
id = "12345abcde"
}
Using terraform import
, import aws_api_gateway_rest_api
using the REST API ID. For example:
% terraform import aws_api_gateway_rest_api.example 12345abcde