An HTTP API Gateway serves as an entry point for your application, routing HTTP traffic to your compute resources. It can be integrated with functions, batch jobs, and multi-container workloads.
Each API gateway is secured with TLS by default. You can also configure a custom domain name, enable CORS, or place a CDN in front of your gateway.
When to use them
HTTP API Gateways are a good fit for any modern web application, from a simple "front door" for a lightweight service to a powerful backend API with authorization and monitoring.
Advantages
- Pay-per-use: You are only charged for the number of requests your gateway processes (from $0.90 to $1.00 per million requests).
- Scalability: The gateway scales automatically to handle thousands of requests per second.
- Security: Each gateway is secured with TLS by default.
- High availability: API Gateway has a 99.95% monthly uptime SLA.
- Ease of use: You can integrate a gateway with your compute resources with just a few lines of configuration.
Disadvantages
- Limited routing: HTTP API Gateways only support path-based routing. If you need to route requests based on query parameters, IP addresses, or HTTP headers, consider using an Application Load Balancer instead.
Basic usage
HttpApiGatewayAPI referencetypeRequired
Type: string "http-api-gateway"
properties.payloadFormat
Lambda event payload format. 2.0 is simpler and recommended for new projects.
Type: string ENUM
Possible values: 1.02.0
Only used if not overridden at the integration level.
properties.cors
CORS settings. Overrides any CORS headers from your application code.
Type: HttpApiCorsConfig
properties.logging
Access logging (request ID, IP, method, status, etc.). Viewable with stacktape logs.
Type: HttpApiAccessLogsConfig
properties.customDomains
Custom domains (e.g., api.example.com). Stacktape auto-creates DNS records and TLS certificates.
Type: Array of DomainConfiguration
Your domain must be added as a Route53 hosted zone in your AWS account first.
properties.cdn
Put a CDN (CloudFront) in front of this API for caching and lower latency worldwide.
Type: CdnConfiguration
properties.alarms
Alarms for this API Gateway (merged with global alarms from the Stacktape Console).
Type: Array of HttpApiGatewayAlarm
properties.disabledGlobalAlarms
Global alarm names to exclude from this API Gateway.
Type: Array of string
overrides
Escape hatch to modify the underlying CloudFormation resources Stacktape creates.
Type: Object
Use dot-notation paths to override specific properties on any child resource.
Find resource logical IDs with stacktape stack-info --detailed.
overrides:
MyDbInstance:
Properties.StorageEncrypted: true
You don't need to specify any properties to create a basic HTTP API Gateway.
Integrating with compute resources
You can forward requests from an API gateway to your compute resources by creating an event integration on a multi-container workload, function, or batch job.
Each integration must specify:
httpApiGatewayName: The name of the API gateway.path: A path pattern that the request must match.method: The HTTP method that the request must match.
If multiple integrations match a request, the most specific one is chosen.
This example shows two integrations:
- The first forwards all requests (
/{proxy+}) to a multi-container workload. - The second, which is more specific, forwards
GETrequests for/invoke-my-functionto a Lambda function.
An HTTP API Gateway with integrations for both a function and a multi-container workload.
For more information, see the documentation on integrating API gateways with functions and multi-container workloads.
CORS
Cross-Origin Resource Sharing (CORS) is a security feature that controls how web browsers handle requests to a different domain than the one the user is currently on. If your frontend and backend are on different domains (e.g., mydomain.com and api.mydomain.com), you'll need to configure CORS.
If you are already handling CORS in your application code, you don't need to enable it in your Stacktape configuration.
You can enable CORS with a single line:
You can also customize the CORS headers:
Enable CORS. With no other options, uses permissive defaults (* origins, common headers).
HttpApiCorsConfigAPI referenceParent:HttpApiGatewayenabledRequired
Enable CORS. With no other options, uses permissive defaults (* origins, common headers).
Type: boolean
allowedOriginsDefault: *
Allowed origins (e.g., https://myapp.com). Use * for any origin.
Type: Array of string
allowedHeaders
Allowed request headers in CORS preflight.
Type: Array of string
allowedMethods
Allowed HTTP methods. Auto-detected from integrations if not set.
Type: Array of string ENUM
Possible values: *DELETEGETHEADOPTIONSPATCHPOSTPUT
allowCredentials
Allow cookies/auth headers in cross-origin requests.
Type: boolean
exposedResponseHeaders
Response headers accessible to browser JavaScript.
Type: Array of string
maxAge
How long (seconds) browsers can cache preflight responses.
Type: number
Custom domain names
You can use a custom domain for your API gateway. If you don't have one, you can register one through Stacktape.
If you already have a domain, you can either let Stacktape manage it (if you use AWS Route 53 for DNS) or use a third-party DNS provider.
For more details, see the Domains and Certificates page.
Using Stacktape to manage domains and certs
Your domain must be added as a Route53 hosted zone in your AWS account first.
DomainConfigurationAPI referenceParent:HttpApiGateway or CdnConfigurationdomainNameRequired
Your domain name (e.g., mydomain.com or api.mydomain.com).
Type: string
Don't include the protocol (https://). The domain must have a Route53 hosted zone
in your AWS account, with your registrar's nameservers pointing to it.
Stacktape automatically creates a DNS record and provisions a free TLS certificate.
customCertificateArn
Use your own TLS certificate instead of the auto-generated one.
Type: string
Provide the ARN of an ACM certificate from your AWS account. Only needed if you have specific certificate requirements (e.g., EV/OV certs). By default, Stacktape provisions and renews free certificates automatically.
disableDnsRecordCreation
Skip DNS record creation for this domain.
Type: boolean
Set to true if you manage DNS records yourself (e.g., through Cloudflare or another DNS provider).
Stacktape will still provision the TLS certificate but won't touch your DNS.
Using a 3rd-party DNS
To use a domain from a provider like GoDaddy or Cloudflare:
- Create or import a TLS certificate for your domain in the AWS Certificate Manager console and copy its ARN.
- Add the
customDomainsconfiguration to your API gateway, using the certificate ARN and disabling DNS record creation.
- After deploying, find the API gateway's domain name in the Stacktape Console.
- In your DNS provider's dashboard, create a
CNAMEorALIASrecord pointing to the API gateway's domain name.
Access logs
Access logs contain basic information about requests to your API gateway, which can be useful for auditing and compliance. Stacktape enables access logging by default, with a retention period of 30 days.
Access logging (request ID, IP, method, status, etc.). Viewable with stacktape logs.
HttpApiAccessLogsConfigAPI referenceParent:HttpApiGatewaydisabled
Disable access logging.
Type: boolean
formatDefault: JSON
Log format. Logs include: requestId, IP, method, status, protocol, responseLength.
Type: string ENUM
Possible values: CLFCSVJSONXML
retentionDaysDefault: 30
How many days to keep logs.
Type: number ENUM
Possible values: 13571430609012015018036540054573118273653
logForwarding
Forward logs to an external service (Datadog, Highlight.io, or any HTTP endpoint).
Type: HttpEndpointLogForwarding or HighlightLogForwarding or DatadogLogForwarding
Uses Kinesis Data Firehose (~$0.03/GB). Failed deliveries go to a backup S3 bucket.
CDN
You can place an AWS CloudFront CDN in front of your API gateway to cache responses and reduce latency.
Put a CDN (CloudFront) in front of this API for caching and lower latency worldwide.
For more information, see the CDN documentation.
Referenceable parameters
The following parameters can be easily referenced using $ResourceParam directive directive.
To learn more about referencing parameters, refer to referencing parameters.
Default domain name
- Usage:
$ResourceParam('<<resource-name>>', 'domain')
Default URL
- Usage:
$ResourceParam('<<resource-name>>', 'url')
Comma-separated list of custom domain names assigned to the HTTP Api Gateway (only available if you use custom domain names)
- Usage:
$ResourceParam('<<resource-name>>', 'customDomains')
Comma-separated list of custom domain name URLs (only available if you use custom domain names)
- Usage:
$ResourceParam('<<resource-name>>', 'customDomainUrls')
URL of the first custom domain name connected to this resource (only available if you use custom domain names)
- Usage:
$ResourceParam('<<resource-name>>', 'customDomainUrl')
Default domain of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnDomain')
Default url of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnUrl')
Comma-separated list of custom domain names assigned to the CDN (only available if you configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnCustomDomains')
Comma-separated list of custom domain name URLs of the CDN (only available if you configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnCustomDomainUrls')