A Stacktape HTTP API Gateway creates a managed, serverless HTTP endpoint that routes requests to Lambda functions and container workloads through HTTP API integrations. It uses AWS API Gateway V2 (HTTP API) — no servers to provision, automatic TLS, built-in throttling, and pay-per-request pricing at ~$1 per million requests.
When to use
HTTP API Gateway is the default choice for building serverless APIs on Stacktape. Use it when your backend is one or more Lambda functions that need a public HTTPS URL with path-based routing. The pay-per-request model makes it cost-effective for APIs with variable or low-to-moderate traffic — you pay nothing when no requests arrive.
Common patterns that fit well:
- REST or RPC APIs backed by Lambda functions — each route maps to a function
- Single-function catch-all — one Lambda handles all routes (e.g., a Hono, Express, or FastAPI app) with a greedy path like
/{proxy+} - Mixed backend — some routes go to Lambda functions, others to container workloads through the same API endpoint
- Spiky or unpredictable traffic — pay-per-request scales from zero to thousands of requests per second without capacity planning
When NOT to use
- Container-based services that stay running — an Application Load Balancer is a better fit for web services. ALBs offer richer routing (headers, query params, source IPs) and a flat hourly cost that's cheaper at sustained high throughput.
- Sustained high-volume APIs (roughly above 50–100 million requests/month) — ALB's flat pricing becomes more economical than pay-per-request at that scale.
- WebSocket or persistent connections — this HTTP API resource routes request-response traffic only. Use a WebSocket API Gateway for Lambda-backed real-time routes, or an Application Load Balancer for a persistent container server.
- TCP/TLS (non-HTTP) protocols — use a Network Load Balancer instead.
| Feature | HTTP API Gateway | Application Load Balancer |
|---|---|---|
| Pricing model | ~$1/million requests | Flat hourly charge + LCU-based |
| Best for | Lambda functions | Container workloads |
| Scales to zero cost | ✓ | ✕ |
| Routing options | Method + path | Method, path, headers, query params, source IPs |
| Route-level authorizers | ✓ | ✕ |
| CDN attachable | ✓ | ✓ |
Basic example
An HTTP API Gateway resource on its own is just the entry point — it does not define routes. Routes are defined on the compute resources (Lambda functions or container workloads) that reference the gateway by name. The simplest setup is a gateway plus one or more Lambda functions with HTTP triggers.
The gateway myApi has no configuration because TLS is included and access logging is enabled by default. The getUsers Lambda function registers a GET /users route on the gateway through its HttpApiIntegration event.
You can reference the deployed gateway URL with $ResourceParam('myApi', 'url') in your config. To surface the URL in terminal output after every deploy, add it to stackConfig.outputs.
Routing
Routes are not defined on the HTTP API Gateway itself. Instead, each compute resource declares which gateway it connects to, which HTTP method to match, and which path pattern to handle. This keeps routing co-located with the code that serves each route.
A single gateway can serve routes from many Lambda functions and container workloads. Each integration specifies a method and a path. Supported methods are GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, and * (any method). Paths support three patterns:
| Pattern | Example | Behavior |
|---|---|---|
| Exact path | /users | Matches only /users |
| Path parameter | /users/{id} | Matches /users/123; id available in event.pathParameters |
| Greedy (catch-all) | /api/{proxy+} | Matches any path starting with /api/ |
Routes are matched by specificity — exact paths take priority over wildcard paths. For container workloads, the HTTP API integration also requires containerPort, because API Gateway must know which container port receives the request. See HTTP triggers for the full integration API, including the container workload integration shape.
Catch-all pattern
For frameworks like Hono, Express, or FastAPI that handle routing internally, use a single Lambda with a greedy path:
This routes every request to a single Lambda. The framework inside the Lambda handles path matching, middleware, and responses. This is the most common pattern for building APIs with Stacktape.
Route authorization
Each HTTP API integration can optionally define an authorizer. Authorization runs before the integration. Rejection status depends on the authorizer and failure: IAM uses 403 Forbidden, so do not assume every denial is 401. Check the authorizer type and response mode. Authorization is configured per-route on the integration, not on the gateway itself. See HTTP triggers for the supported authorizer types and configuration details.
CORS
Cross-Origin Resource Sharing (CORS) controls which browser-based frontends can call your API from a different domain. When CORS is enabled on the gateway, API Gateway handles preflight OPTIONS requests automatically — this overrides any CORS headers your application code sets.
When enabled is true with no other options, the gateway uses permissive defaults: * for allowed origins and common headers. The allowedMethods are auto-detected from the integrations attached to the gateway, so you typically don't need to set them manually.
Set allowCredentials: true if your frontend sends cookies or Authorization headers in cross-origin requests — note that this requires listing specific origins rather than using *. The maxAge property (in seconds) controls how long browsers cache preflight responses; setting it to 86400 (24 hours) reduces preflight overhead for frequently-called APIs.
Custom domains
Stacktape can attach your own domain (e.g., api.example.com) to an HTTP API Gateway. Stacktape automatically provisions a free TLS certificate and creates a DNS record in Route53. Your domain must have a Route53 hosted zone in your AWS account — use stacktape domain add to set one up.
You can attach multiple domains to a single gateway. Each domain gets its own certificate, managed and auto-renewed by AWS. If you manage DNS records yourself, set disableDnsRecordCreation: true and Stacktape will provision the TLS certificate but skip creating the DNS record in Route53. If you have specific certificate requirements, provide customCertificateArn with an ACM certificate ARN from your AWS account; otherwise Stacktape provisions and renews free certificates automatically.
For full details on domain management, see Custom domains.
CDN
The cdn property attaches a CDN (CloudFront) in front of the HTTP API Gateway, placing a global caching and edge-delivery layer before your API. This reduces latency for geographically distributed users and offloads repeated requests from your backend.
When to enable CDN: Your API serves cacheable public data (product catalogs, configuration endpoints, public content), or your users are spread across multiple continents and you need lower global latency.
When to skip CDN: Most Lambda-backed APIs return dynamic, user-specific data that isn't cacheable. Adding a CDN to a fully dynamic API adds CloudFront request and data-transfer charges, and cached behavior adds invalidation and propagation considerations. For APIs serving only authenticated, personalized responses, the default direct API Gateway endpoint is sufficient.
Setting enabled: true activates the CDN. The cloudfrontPriceClass controls which CloudFront edge regions serve traffic — PriceClass_100 (North America + Europe, cheapest), PriceClass_200 (adds Asia, Middle East, Africa), or PriceClass_All (all regions worldwide). WAF protection for CDN-backed APIs is configured on the CDN layer — see CDN and Web Application Firewall for details.
See CDN for the full CDN configuration surface, including caching behavior, custom domains on the CDN itself, edge functions, and route rewrites.
Access logging
HTTP API Gateway logs every request by default. Logs include request ID, client IP, HTTP method, status code, protocol, and response length. View logs with stacktape logs or in the Stacktape Console.
The format property controls the log output shape — JSON (default), CLF (Common Log Format), XML, or CSV. JSON is the most practical for programmatic analysis and integrates well with log forwarding. The retentionDays property defaults to 30. Allowed values are: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, or 3653 days.
HTTP API access logs support the shared log-forwarding configuration surface for sending logs to external services. See Log forwarding for setup details.
To disable access logging entirely (not recommended for production), set disabled: true.
Payload format
The payload format controls the shape of the event object your Lambda function receives from API Gateway. There are two versions:
| Version | Best for |
|---|---|
1.0 | Legacy integrations, existing code expecting the v1 event shape |
2.0 | New projects — simpler, flatter event structure with less parsing code |
When not set at the gateway level, the effective default is determined by each integration — integrations default to 1.0 unless overridden. You can set the format at the gateway level (applies to all routes unless an individual integration overrides it) or set it per-route on individual integrations.
2.0. The simplified event structure requires less parsing code and is the format AWS recommends going forward. Frameworks like Hono's AWS Lambda adapter handle both formats transparently.Alarms
Stacktape supports two alarm types for HTTP API Gateway: error rate (percentage of 4xx/5xx responses) and latency (request-to-response time). Alarm notification targets are configured per-alarm through the shared notification integrations — supported targets include Slack, Microsoft Teams, email, Discord, and webhook. Define alarms in the resource config and deploy to apply changes. Export legacy Console rules into config.
With the example settings and the default comparison operator (GreaterThanThreshold), the error-rate alarm fires when 4xx/5xx error rate is greater than 5%, and the latency alarm fires when p95 latency is greater than 3000 ms. For the latency alarm, the statistic property controls how the metric is aggregated — avg (default), p90, p95, p99, min, max, or sum. The error rate alarm does not support statistic. Both alarm types support a custom comparisonOperator: GreaterThanThreshold (default), GreaterThanOrEqualToThreshold, LessThanThreshold, and LessThanOrEqualToThreshold.
You can fine-tune alarm sensitivity with the evaluation property: set the evaluation period (default 60 seconds), evaluationPeriods (how many recent periods to examine), and breachedPeriods (how many must breach to fire). This prevents alarms from firing on brief spikes.
To exclude specific legacy Console rules during migration, list their names in disabledGlobalAlarms. For more on alarm configuration, see Alarms.
Referenceable parameters
Use $ResourceParam('myApi', 'paramName') in your config to reference gateway values after deployment.
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')
API Reference
HttpApiGatewayPropsHTTP API Gateway FAQ
How much does AWS API Gateway HTTP API cost?
AWS API Gateway V2 (HTTP API) costs ~$1 per million requests with no minimum fee or hourly charge. You pay only for the requests your API receives. Data transfer out is billed separately at standard AWS rates. There's a free tier of 1 million requests per month for the first 12 months.
How do I add routes to my HTTP API Gateway?
Routes are not defined on the gateway resource. Instead, attach HttpApiIntegration events to your Lambda functions or container workloads, referencing the gateway by its resource name. Each integration specifies an HTTP method and URL path. For container workloads, the integration also requires a containerPort. See HTTP triggers for the full integration API.
When should I use HTTP API Gateway vs an Application Load Balancer?
Use HTTP API Gateway for Lambda-based APIs with variable traffic — you pay per request and scale to zero. Use an Application Load Balancer for container-based web services with sustained traffic — the flat hourly cost plus LCU-based pricing is cheaper above roughly 50–100 million requests per month. ALBs also support richer routing rules (headers, query params, source IPs).
Does HTTP API Gateway support WebSockets?
No. This HTTP API Gateway resource routes request-response HTTP traffic by method and path. For real-time messaging, use a WebSocket API Gateway with Lambda routes. Use an Application Load Balancer when you run a persistent container WebSocket server such as Socket.IO or ws.
What is the maximum payload size for HTTP API Gateway?
AWS API Gateway V2 (HTTP API) has a maximum payload size of 10 MB for both requests and responses. For larger payloads, use S3 presigned URLs to upload/download files directly, or use an Application Load Balancer which does not have this limit.
Can I protect my API Gateway with a firewall?
The HttpApiGateway resource does not expose a top-level useFirewall property. To add WAF protection, enable cdn on the gateway and attach a WebAppFirewall resource to the CDN distribution. This provides rate limiting, IP filtering, geo-blocking, and bot protection at the edge layer in front of your API. See the CDN and Web Application Firewall pages for configuration details.