aws.apigatewayv2-api resource

Description

Api manages an API Gateway v2 API, the root of an HTTP or WebSocket API: its protocol, name, selection expressions, CORS configuration, and tags, plus the OpenAPI import that can populate it. The protocol is fixed at create time. The quick-create trio (target, route-key, credentials-arn) rides the create call only and materializes an integration, a catch-all route, and an auto-deployed default stage that this resource does not manage afterward, so a change to any of the three replaces the API. An OpenAPI body is applied with ReimportApi, which replaces the API's routes and integrations and overwrites API-level properties from the document; the resource then re-asserts the configured name, description, version, CORS, and tags, so a value set in configuration wins over the document.

Source: internal/service/apigatewayv2/api_rsrc.go:32

Example usage:

imports: {
  aws: 'github.com/cloudboss/unobin-library-aws'
}

resources: {
  example: aws.apigatewayv2-api {
    # Set input fields here.
  }
}

Inputs

name

string

required

Name identifies the API, 1 to 128 characters. The bound is checked in validate, since AWS counts characters and the constraint layer counts bytes.

protocol-type

string

required

ProtocolType is HTTP or WEBSOCKET and cannot change on an existing API. It decides what else may be set: the quick-create trio, the CORS block, and the OpenAPI import are HTTP-only features.

api-key-selection-expression

optional(string)

ApiKeySelectionExpression is meaningful for WebSocket APIs, though AWS stores and echoes it for HTTP APIs too. Unset leaves the server default, $request.header.x-api-key.

cors-configuration

optional(object)

optional(
  object({
    allow-credentials: optional(boolean)
    allow-headers: optional(list(string))
    allow-methods: optional(list(string))
    allow-origins: optional(list(string))
    expose-headers: optional(list(string))
    max-age: optional(integer)
  })
)

CorsConfiguration is the CORS configuration of an HTTP API. Removing the block deletes the configuration with its own call; changing it replaces the whole Cors object.

credentials-arn

optional(string)

CredentialsArn is part of quick create: the credentials the quick-created integration uses, for HTTP APIs only. It rides the create call alone and the API never echoes it back, so out-of-band drift on it is undetectable and a change replaces the API.

description

optional(string)

Description is at most 1024 characters, checked in validate. Removing it leaves the stored description alone.

disable-execute-api-endpoint

optional(boolean)

DisableExecuteApiEndpoint turns off the default execute-api endpoint so clients must use a custom domain name. Unset leaves the cloud value alone; an explicit false re-enables the default endpoint.

disable-schema-validation

optional(boolean)

DisableSchemaValidation skips request-body schema validation, for WebSocket APIs only; AWS rejects it elsewhere. Unset leaves the cloud value alone; an explicit false re-enables validation.

ip-address-type

optional(string)

IpAddressType is ipv4 or dualstack. Unset lets the server choose (ipv4) and, on update, leaves the cloud value alone.

route-key

optional(string)

RouteKey is part of quick create: the key of the quick-created route, for HTTP APIs only, defaulting to the $default catch-all. Like the rest of the trio it is write-only and a change replaces the API.

route-selection-expression

optional(string)

RouteSelectionExpression routes requests to WebSocket routes, such as $request.body.action. HTTP APIs accept only "$request.method $request.path", which is also the server default.

target

optional(string)

Target is part of quick create: a URL for an HTTP_PROXY integration or a Lambda function ARN for AWS_PROXY, HTTP APIs only. Write-only; a change replaces the API.

version

optional(string)

Version is a version identifier, 1 to 64 characters, checked in validate.

body

optional(string)

Body is an OpenAPI definition, JSON or YAML, for an HTTP API. It is applied by import, which replaces the API's routes and integrations and overwrites API-level properties from the document; the configured name, description, version, CORS, and tags are re-asserted after each import. Removing the body makes no call, leaving the imported routes in place.

base-path

optional(string)

BasePath tells an import how to interpret the base path of the document: ignore, prepend, or split. It parameterizes the import call (the SDK member is spelled Basepath), so changing it by itself does nothing.

fail-on-warnings

optional(boolean)

FailOnWarnings makes the import fail when the document produces warnings; by default warnings are tolerated. It rides the import call only, so changing it by itself does nothing.

tags

map(string)

Tags label the API. A document with its own tags section replaces the API's tag set on import, so the resource re-syncs this map after every import: tags belong here rather than in the body.

Input Constraints

Protocol type rules

protocol-type must be HTTP or WEBSOCKET.

Rule logic

Require

input.protocol-type == 'HTTP'
|| input.protocol-type == 'WEBSOCKET'

cors-configuration, credentials-arn, route-key, target, body, and fail-on-warnings are supported only for HTTP APIs.

Rule logic

When

input.protocol-type == 'WEBSOCKET'

Require

input.cors-configuration == null
&& input.credentials-arn == null
&& input.route-key == null
&& input.target == null
&& input.body == null
&& input.fail-on-warnings == null

route-selection-expression is required for a WebSocket API.

Rule logic

When

input.protocol-type == 'WEBSOCKET'

Require

input.route-selection-expression != null

route-selection-expression for an HTTP API must be $request.method $request.path.

Rule logic

When

input.protocol-type == 'HTTP'
&& input.route-selection-expression != null

Require

input.route-selection-expression == '$request.method $request.path'

Ip address type rules

ip-address-type must be ipv4 or dualstack.

Rule logic

When

input.ip-address-type != null

Require

input.ip-address-type == 'ipv4'
|| input.ip-address-type == 'dualstack'

Api key selection expression rules

api-key-selection-expression must be $context.authorizer.usageIdentifierKey or $request.header.x-api-key.

Rule logic

When

input.api-key-selection-expression != null

Require

input.api-key-selection-expression == '$context.authorizer.usageIdentifierKey'
|| input.api-key-selection-expression == '$request.header.x-api-key'

Base path rules

base-path must be ignore, prepend, or split.

Rule logic

When

input.base-path != null

Require

input.base-path == 'ignore'
|| input.base-path == 'prepend'
|| input.base-path == 'split'

Field combinations

fail-on-warnings applies only to a body import.

base-path applies only to a body import.

Outputs

api-id

string

api-endpoint

string

arn

string