HTTP API Gateways



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 reference
typeRequired
No description

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.

resources:
  myHttpApi:
    type: '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 GET requests for /invoke-my-function to a Lambda function.
resources:
  myHttpApi:
    type: http-api-gateway

  myFunction:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: 'path/to/my-lambda.ts'
      events:
        - type: http-api-gateway
          properties:
            httpApiGatewayName: 'myHttpApi'
            path: '/invoke-my-function'
            method: 'GET'

  mySingleContainer:
    type: 'multi-container-workload'
    properties:
      containers:
        - name: 'myAppContainer'
          packaging:
            type: stacktape-image-buildpack
            properties:
              entryfilePath: '_example-configs/containers/ts-container.ts'
          environment:
            - name: port
              value: 80
          events:
            - type: 'http-api-gateway'
              properties:
                httpApiGatewayName: 'myHttpApi'
                containerPort: 80
                path: /{proxy+} # greedy path
                method: '*'
      resources:
        cpu: 0.25
        memory: 512

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:

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cors:
        enabled: true

You can also customize the CORS headers:

Enable CORS. With no other options, uses permissive defaults (* origins, common headers).

HttpApiCorsConfigAPI referenceParent:HttpApiGateway
enabledRequired

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 CdnConfiguration
domainNameRequired

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.

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      customDomains:
        - domainName: whatever.mydomain.com

Using a 3rd-party DNS

To use a domain from a provider like GoDaddy or Cloudflare:

  1. Create or import a TLS certificate for your domain in the AWS Certificate Manager console and copy its ARN.
  2. Add the customDomains configuration to your API gateway, using the certificate ARN and disabling DNS record creation.
resources:
  myWebsite:
    type: http-api-gateway
    properties:
      customDomains:
        - domainName: mydomain.com
          disableDnsRecordCreation: true
          customCertificateArn: <<ARN_OF_YOUR_CERTIFICATE>>
  1. After deploying, find the API gateway's domain name in the Stacktape Console.
  2. In your DNS provider's dashboard, create a CNAME or ALIAS record 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:HttpApiGateway
disabled

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.

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      logging:
        format: CSV

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.

domain
  • Default domain name

  • Usage: $ResourceParam('<<resource-name>>', 'domain')
url
  • Default URL

  • Usage: $ResourceParam('<<resource-name>>', 'url')
customDomains
  • 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')
customDomainUrls
  • Comma-separated list of custom domain name URLs (only available if you use custom domain names)

  • Usage: $ResourceParam('<<resource-name>>', 'customDomainUrls')
customDomainUrl
  • URL of the first custom domain name connected to this resource (only available if you use custom domain names)

  • Usage: $ResourceParam('<<resource-name>>', 'customDomainUrl')
cdnDomain
  • Default domain of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).

  • Usage: $ResourceParam('<<resource-name>>', 'cdnDomain')
cdnUrl
  • Default url of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).

  • Usage: $ResourceParam('<<resource-name>>', 'cdnUrl')
cdnCustomDomains
  • 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')
cdnCustomDomainUrls
  • 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')