Http Api Gateways

Overview

Http api gateways represent entry-points to your application from an outer internet. They route traffic to your application and integrate easily with workloads of your stack: functions, batch-jobs or container-workloads.

Http api gateways are used to communicate with your workloads using HTTP protocol.
Each api gateway is secured by TLS by default.
You can easily configure custom domain names, CORS or put CDN in-front of your gateway.

When to use

Http api gateway is a great fit for any modern web app. Whether you only need "front door" to your lightweight application or you are building powerful API backend with authorization, access control and API monitoring, http api gateway can meet your needs.

Advantages

Pay-per-use - You are NOT paying for http-api-gateway being deployed. You are only paying for the number of requests processed by the gateway. AWS charges from $0.90 to $1.00 per million requests.
Scaling - Gateway scales with your needs. It can process thousands of requests per second. Moreover, rate limit can be increased upon request.
Security - Each gateway is secured using TLS by default.
Availability - Monthly Uptime Percentage of at least 99.95% for each AWS region, during any monthly billing cycle.
Ease of use - Integrate with workloads of your stack with 3 lines of config

Disadvantages

Http api gateway only supports path-based routing, i.e developers can configure which resources will receive incoming API requests based on the URL requested by the client. In comparison, load balancers also support routing based on query paramters, ip address or routing based on HTTP headers in the request.

Usage

HttpApiGateway API reference

payloadFormat

string ENUM

default payload format for attached integrations

cors

HttpApiCorsConfig

cors setting for gateway

accessLogs

HttpApiAccessLogsConfig

specifies logging settings of the http-api-gateway

domainNames

Array of DomainConfiguration

specifies domain names which should be attached to the http-api-gateway

cdn

CdnConfiguration

enables you to put CDN in front of http-api-gateway

➡️ Simple usage

By default http-api-gateway does not need to have any properties defined. Definition can be simple as in the following example.


resources:
  myHttpApi:
    Type: 'http-api-gateway'

Integrating with workloads

In this example we are integrating myHttpApi with myLambda function and mySingleContainer container workload.

Requests incoming to myHttpApi are routed as follows:

all GET requests with url path /invoke-my-lambda are routed to myLambda.
any other requests are routed to mySingleContainer container workload


resources:
  myHttpApi:
    Type: http-api-gateway

  myLambda:
    Type: function
    Properties:
      filePath: 'path/to/my-lambda.ts'
      events:
        - type: http-api-gateway
          properties:
            httpApiGatewayName: 'myHttpApi'
            path: '/invoke-my-lambda'
            method: 'GET'

  mySingleContainer:
    Type: 'container-workload'
    Properties:
      containers:
        - name: 'myAppContainer'
          imageConfig:
            filePath: '_example-configs/containers/ts-container.ts'
          environment:
            - name: port
              value: 80
          events:
            - type: 'http-api-gateway'
              properties:
                httpApiGatewayName: 'myHttpApi'
                containerPort: 80
                path: '*'
                method: '*'
      resources:
        cpu: 0.25
        memory: 512

More information on integrating workloads with http api can be found:

➡️ Cors

HttpApiCorsConfig API reference

Parent API reference: HttpApiGateway

Required

enabled

boolean

enables cors configuration

allowedOrigins

Array of string

specifies the origins that you want to allow cross-domain requests from

allowedHeaders

Array of string

specifies which headers are allowed

allowedMethods

Array of string ENUM

specifies which methods are allowed for cross-origin requests

allowCredentials

boolean

specifies whether credentials are included in the CORS request

exposedResponseHeaders

Array of string

identifies headers in the response that you want viewer to be able to access from their applications

maxAge

number

specifies the time in seconds that your browser can cache the response for a preflight request


resources:
  myHttpApi:
    Type: 'http-api-gateway'
    Properties:
      cors:
        enabled: true

➡️ Domain names

Domains can be easily controlled by Stacktape.

If your domain DNS records are controlled by AWS Route 53, Stacktape automatically generates correct TLS certifiates for your domain.

If your domain DNS records are NOT controlled by AWS:

migrate domain with a help of domain-add command (if you are migrating domain which is currently in use, please readAWS docs).
you can provision certificate by specifying customCertificateArn and specifyingdisableDnsProvision

DomainConfiguration API reference

Parent API reference: (HttpApiGateway or CdnConfiguration)

Required

domainName

string

fully qualified domain name

customCertificateArn

string

certificate to be provisioned with this domain

disableDnsProvision

boolean

disable creation of dns record


resources:
  myHttpApi:
    Type: 'http-api-gateway'
    Properties:
      domainNames:
        - domainName: whatever.mydomain.com

➡️ Access logs

HttpApiAccessLogsConfig API reference

Parent API reference: HttpApiGateway

Required

enabled

boolean

enables logging of the access logs

format

string ENUM

determines format of the access logs


resources:
  myHttpApi:
    Type: 'http-api-gateway'
    Properties:
      accessLogs:
        enabled: true

➡️ Cdn

CdnConfiguration API reference

Parent API reference: HttpApiGateway

Required

enabled

boolean

enables CDN distribution creation

cachingOptions

CdnCachingOptions

specifies custom caching options

forwardingOptions

CdnForwardingOptions

specifies custom forwarding options

routeRewrites

Array of CdnRouteRewrite

enables you to direct request for specified url paths to different origins

domainNames

Array of DomainConfiguration

custom domain names for cdn distribution

cloudfrontPriceClass

string ENUM

price class can be used to restrict the locations from which CDN serves traffic.

setResponseHeaders

Array of CdnResponseHeader

manually set headers that CDN will automatically add to response

defaultRoutePrefix

string

when used, cdn prefixes every request to the origin with the prefix

errorDocument

string

custom error document url

indexDocument

string

custom index (root) document for the distribution


resources:
  myHttpApi:
    Type: 'http-api-gateway'
    Properties:
      cdn:
        enabled: true

Cdn domain names

Domains can be easily controlled by Stacktape.

If your domain DNS records are controlled by AWS Route 53, Stacktape automatically generates correct TLS certifiates for your domain.

If your domain DNS records are NOT controlled by AWS:

migrate domain with a help of domain-add command (if you are migrating domain which is currently in use, please readAWS docs).
you can provision certificate by specifying customCertificateArn and specifyingdisableDnsProvision

DomainConfiguration API reference

Parent API reference: CdnConfiguration

Required

domainName

string

fully qualified domain name

customCertificateArn

string

certificate to be provisioned with this domain

disableDnsProvision

boolean

disable creation of dns record


resources:
  myHttpApi:
    Type: 'http-api-gateway'
    Properties:
      cdn:
        enabled: true
        domainNames:
          - domainName: mydomain.com

Route rewrites

Route rewrites can be used to route request coming to different origins: I.e instead of forwarding request to the http-api-gateway, you can choose other resource to route to (http-api-gateway, bucket or load-balancer).

CdnRouteRewrite API reference

Parent API reference: CdnConfiguration

Required

path

string

the path pattern that specifies which requests this route rewrite applies to

routePrefix

string

when used, cdn route rewrite prefixes every request to the origin with the prefix

routeTo

(CdnLoadBalancerRoute or CdnHttpApiGatewayRoute or CdnBucketRoute)

determines origin to which this route rewrite forwards requests

setResponseHeaders

Array of CdnResponseHeader

manually set headers that CDN will automatically add to response

cachingOptions

CdnCachingOptions

specifies custom caching options for the route rewrite

forwardingOptions

CdnForwardingOptions

specifies custom forwarding options for the route rewrite

Routing to bucket

CdnBucketRoute API reference

Parent API reference: CdnRouteRewrite

Required

type

string "bucket"

Type of the resource

Required

properties.bucketName

string

name of the bucket

properties.disableUrlNormalization

boolean

url normalization enables you to use clean urls without .html extensions

In the following example we are routing all request with url path starting with /static to the bucket myBucket which contains our static content. All other requests are routed to the http-api-gateway myHttpApi.


resources:
  myHttpApi:
    Type: 'http-api-gateway'
    Properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /static/*
            routeTo:
              type: bucket
              properties:
                bucketName: myBucket
                disableUrlNormalization: true

  myBucket:
    Type: 'bucket'

Routing to application-load-balancer

CdnLoadBalancerRoute API reference

Parent API reference: CdnRouteRewrite

Required

type

string "application-load-balancer"

Type of the resource

Required

properties.loadBalancerName

string

name of the load balancer

Required

properties.listenerPort

number

port of load balancer listener

properties.originDomainName

string

explicitly set origin domain name you wish to use when forwarding to load balancer

In the following example we are routing all request with url path starting with /app2 to the load-balancer myLoadBalancer. All other requests are routed to the http-api-gateway myHttpApi.


resources:
  myHttpApi:
    Type: 'http-api-gateway'
    Properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /app2/*
            routeTo:
              type: 'application-load-balancer'
              properties:
                loadBalancerName: myLoadBalancer
                listenerPort: 443

  myLoadBalancer:
    Type: 'application-load-balancer'
    Properties:
      listeners:
        - port: 443
          protocol: HTTPS

Routing to http-api-gateway

CdnHttpApiGatewayRoute API reference

Parent API reference: CdnRouteRewrite

Required

type

string "http-api-gateway"

Type of the resource

Required

properties.httpApiGatewayName

string

name of the http-api-gateway

In the following example we are routing all request with url path starting with /app2 to the http-api-gateway appApiGateway. All other requests are routed to the http-api-gateway myHttpApi.


resources:
  myHttpApi:
    Type: 'http-api-gateway'
    Properties:
      cdn:
        enabled: true
        routeRewrites:
          - path: /app2/*
            routeTo:
              type: 'http-api-gateway'
              properties:
                httpApiGatewayName: appApiGateway

  appApiGateway:
    Type: 'http-api-gateway'

Caching options

Caching options enable you to specify caching settings for your CDN.

You can specify different cache options for each route rewrite. This gives you ability to cache different types of content differently.

If you do not specify caching options, Stacktape uses default caching options.

CdnCachingOptions API reference

Parent API reference: (CdnConfiguration or CdnRouteRewrite)

cacheMethods

Array of string ENUM

only responses to specified methods will be cached

minTTL

number

the minimum amount of time, in seconds, that you want objects to stay in the CDN cache before it sends another request to the origin

maxTTL

number

The maximum amount of time, in seconds, that objects stay in the CDN cache before it sends another request to the origin to see if the object has been updated.

defaultTTL

number

The default amount of time, in seconds, that you want objects to stay in the CDN cache before it sends another request to the origin to see if the object has been updated.

disableCompression

boolean

if enabled, CDN will automatically compress certain files returned from origin before returning to viewer

disableAcceptEncodingBrotli

boolean

determines whether CDN can use Brotli compression

disableAcceptEncodingGzip

boolean

determines whether CDN can use Gzip compression

cacheKeyParameters

CdnCacheKey

specifies HTTP headers, cookies, and URL query strings to include in the cache key

In the following example we are setting default TTL for the default route to 60 seconds. However, every request with url path starting with /static will be cached for 604800 seconds (1 week).


resources:
  myHttpApi:
    Type: 'http-api-gateway'
    Properties:
      cdn:
        enabled: true
        cachingOptions:
          defaultTTL: 60
        routeRewrites:
          - path: /static/*
            cachingOptions:
              defaultTTL: 604800

Specify cache key

Cache key specifies which parts of request are included in the cache key.

By default requests are cached only based on path.

You can configure cache key to include headers, cookies or query params.

CdnCacheKey API reference

Parent API reference: CdnCachingOptions

CacheKeyCookies

specifies if and which cookies are included in cache key

headers

CacheKeyHeaders

specifies if and which headers are included in cache key

queryString

CacheKeyQueryString

specifies if and which query parameters are included in cache key

Cache key headers

CacheKeyHeaders API reference

Parent API reference: CdnCacheKey

none

boolean

if set to true, no headers are included in cache key

whitelist

Array of string

only the headers listed are included in the cache key

Cache key cookies

CacheKeyCookies API reference

Parent API reference: CdnCacheKey

none

boolean

if set to true, no cookies are included in cache key

whitelist

Array of string

only the cookies listed are included in the cache key

allExcept

Array of string

all cookies except the ones listed are included in the cache key

all

boolean

if set to true, all cookies are included in cache key

Cache key query string

CacheKeyQueryString API reference

Parent API reference: CdnCacheKey

all

boolean

if set to true, all query params are included in cache key

none

boolean

if set to true, no query params are included in cache key

whitelist

Array of string

only the query params listed are included in the cache key

Forwarding options

Forwarding options enable you to specify which parts of request get forwarded to the origin.

You can specify different forwarding options for each route rewrite. This gives you ability to forward parts of request only when needed.

If you do not specify forwarding options, Stacktape uses default forwarding options.

CdnForwardingOptions API reference

Parent API reference: (CdnConfiguration or CdnRouteRewrite)

customRequestHeaders

Array of CdnCustomRequestHeader

manually set headers which CDN will include when sending request to origin

allowedMethods

Array of string ENUM

specifies which methods will be forwarded by CDN to the origin

ForwardCookies

specifies if and which cookies will be forwarded to the origin

headers

ForwardHeaders

specifies if and which headers will be forwarded to the origin

queryString

ForwardQueryString

specifies if and which query params will be forwarded to the origin

In the following example we are configuring CDN to only forward requests with methods GET and

POST.


resources:
  myHttpApi:
    Type: 'http-api-gateway'
    Properties:
      cdn:
        enabled: true
        forwardingOptions:
          allowedMethods:
            - 'GET'
            - 'POST'

Forwarding headers

ForwardHeaders API reference

Parent API reference: CdnForwardingOptions

none

boolean

if set to true, no headers are forwarded to the origin

whitelist

Array of string

only the headers listed are forwarded to the origin

allViewer

boolean

if set to true, all viewer headers are forwarded to the origin

allViewerAndWhitelistCloudFront

Array of string

all viewer headers and additional listed CDN headers are forwarded to the origin

Forwarding cookies

ForwardCookies API reference

Parent API reference: CdnForwardingOptions

none

boolean

if set to true, no cookies are forwarded to the origin

whitelist

Array of string

only the cookies listed are forwarded to the origin

all

boolean

if set to true, all cookies are forwarded to the origin

Forwarding query string

ForwardQueryString API reference

Parent API reference: CdnForwardingOptions

all

boolean

if set to true, all query params are forwarded to the origin

none

boolean

if set to true, no query params are forwarded to the origin

whitelist

Array of string

only the query parameters listed are forwarded to the origin