# api-gateway

Creates an API Gateway V2 (HTTP or WebSocket) API with stages, integrations, routes, and a custom domain.

Provisions an HTTP or WebSocket API with CORS configuration, Lambda proxy (or HTTP_PROXY/MOCK) integrations, typed route key mappings, auto-deploying stages with throttle limits and access logging, and an optional custom domain with ACM TLS and API mapping. For REST (v1) APIs, extend with `aws_api_gateway_rest_api` resources in the calling stack.

## Usage

```hcl
module "api" {
  source  = "hcassc.jfrog.io/iac-terraform-modules-virtual/networking/api-gateway/aws"
  version = "0.1.0"

  name = "my-http-api"

  integrations = {
    lambda = {
      integration_type = "AWS_PROXY"
      integration_uri  = module.lambda.invoke_arns["handler"]
    }
  }

  routes = {
    get_items = {
      route_key       = "GET /items"
      integration_key = "lambda"
    }
  }
}
```

<!-- BEGIN_TF_DOCS — DO NOT EDIT BELOW THIS LINE -->
## Requirements

| Name | Version |
| ---- | ------- |
| <a name="requirement_terraform"></a> [terraform](#requirement_terraform) | ~> 1.5 |
| <a name="requirement_aws"></a> [aws](#requirement_aws) | ~> 6.50 |

## Providers

| Name | Version |
| ---- | ------- |
| <a name="provider_aws"></a> [aws](#provider_aws) | 6.50.0 |

## Resources

| Name | Type |
| ---- | ---- |
| [aws_apigatewayv2_api.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/apigatewayv2_api) | resource |
| [aws_apigatewayv2_api_mapping.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/apigatewayv2_api_mapping) | resource |
| [aws_apigatewayv2_domain_name.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/apigatewayv2_domain_name) | resource |
| [aws_apigatewayv2_integration.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/apigatewayv2_integration) | resource |
| [aws_apigatewayv2_route.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/apigatewayv2_route) | resource |
| [aws_apigatewayv2_stage.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/apigatewayv2_stage) | resource |

## Inputs

| Name | Description | Type | Default | Required |
| ---- | ----------- | ---- | ------- | :------: |
| <a name="input_name"></a> [name](#input_name) | Name for the API | `string` | n/a | yes |
| <a name="input_cors_configuration"></a> [cors_configuration](#input_cors_configuration) | CORS configuration for HTTP APIs | <pre>object({<br/>    allow_origins     = optional(list(string), ["*"])<br/>    allow_methods     = optional(list(string), ["GET", "POST", "PUT", "DELETE", "OPTIONS"])<br/>    allow_headers     = optional(list(string), ["Content-Type", "Authorization"])<br/>    expose_headers    = optional(list(string), [])<br/>    max_age           = optional(number, 86400)<br/>    allow_credentials = optional(bool, false)<br/>  })</pre> | `null` | no |
| <a name="input_custom_domain"></a> [custom_domain](#input_custom_domain) | Custom domain name configuration | <pre>object({<br/>    domain_name         = string<br/>    acm_certificate_arn = string<br/>    endpoint_type       = optional(string, "REGIONAL")<br/>    stage_key           = optional(string, "default")<br/>    api_mapping_key     = optional(string, null)<br/>  })</pre> | `null` | no |
| <a name="input_description"></a> [description](#input_description) | API description | `string` | `""` | no |
| <a name="input_integrations"></a> [integrations](#input_integrations) | Map of API integrations | <pre>map(object({<br/>    integration_type       = string # AWS_PROXY, HTTP_PROXY, MOCK<br/>    integration_uri        = optional(string, null)<br/>    integration_method     = optional(string, "POST")<br/>    payload_format_version = optional(string, "2.0")<br/>    timeout_milliseconds   = optional(number, 29000)<br/>  }))</pre> | `{}` | no |
| <a name="input_protocol_type"></a> [protocol_type](#input_protocol_type) | API type — HTTP or WEBSOCKET | `string` | `"HTTP"` | no |
| <a name="input_routes"></a> [routes](#input_routes) | Map of API routes | <pre>map(object({<br/>    route_key          = string<br/>    integration_key    = optional(string, null)<br/>    authorization_type = optional(string, "NONE")<br/>    authorizer_id      = optional(string, null)<br/>  }))</pre> | `{}` | no |
| <a name="input_stages"></a> [stages](#input_stages) | Map of API stages to deploy | <pre>map(object({<br/>    name                 = string<br/>    auto_deploy          = optional(bool, true)<br/>    throttle_burst_limit = optional(number, 5000)<br/>    throttle_rate_limit  = optional(number, 10000)<br/>    access_log_arn       = optional(string, null)<br/>    access_log_format    = optional(string, "$context.requestId $context.identity.sourceIp $context.httpMethod $context.routeKey $context.status $context.responseLength $context.requestTime")<br/>    default_route_settings = optional(object({<br/>      throttling_burst_limit = optional(number, 5000)<br/>      throttling_rate_limit  = optional(number, 10000)<br/>    }), null)<br/>  }))</pre> | <pre>{<br/>  "default": {<br/>    "name": "$default"<br/>  }<br/>}</pre> | no |
| <a name="input_tags"></a> [tags](#input_tags) | Resource tags to apply to all resources | `map(string)` | `{}` | no |

## Outputs

| Name | Description |
| ---- | ----------- |
| <a name="output_api_endpoint"></a> [api_endpoint](#output_api_endpoint) | Default API endpoint URL |
| <a name="output_arn"></a> [arn](#output_arn) | API Gateway V2 API ARN |
| <a name="output_custom_domain_name"></a> [custom_domain_name](#output_custom_domain_name) | Custom domain name API Gateway hostname (null if not configured) |
| <a name="output_id"></a> [id](#output_id) | API Gateway V2 API ID |
| <a name="output_stage_ids"></a> [stage_ids](#output_stage_ids) | Map of stage logical key to stage ID |
| <a name="output_stage_invoke_urls"></a> [stage_invoke_urls](#output_stage_invoke_urls) | Map of stage logical key to invoke URL |
<!-- END_TF_DOCS — DO NOT EDIT ABOVE THIS LINE -->