Close
logoStacktape docs



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 the 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.

Simple usage

HttpApiGateway  API reference
Required
type
Type: string "http-api-gateway"
Type of the resource
properties.payloadFormat
Type: string ENUM

Determines the shape of the event delivered to your integrations.

properties.accessLogs

Configures the way Http Api access logs are collected and stored

properties.domainNames
Type: Array of DomainConfiguration

Configures domain names attached to this Http Api Gateway

properties.cdn

Configures CDN (Content Delivery Network) to be in front of your Http Api Gateway

overrides
Type: Object

Overrides properties of the specified sub-resource.

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

Following example shows:

  • myHttpApi - HTTP API gateway
  • myLambda function integrated with myHttpApi
  • mySingleContainer container workload integrated with myHttpApi

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
Type: boolean

Enables CORS (Cross-Origin Resource Sharing)

allowedOrigins
Type: Array of string

Origins to accepts cross-domain requests from

allowedHeaders
Type: Array of string

Allowed HTTP headers

allowedMethods
Type: Array of string ENUM

Allowed HTTP methods

allowCredentials
Type: boolean

Configures the presence of credentials in the CORS request

exposedResponseHeaders
Type: Array of string

Response headers that should be made available to scripts running in the browser, in response to a cross-origin request

maxAge
Type: number

Time in seconds that 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 certificates for your domain.

If your domain DNS records are NOT controlled by AWS:

  1. migrate domain with a help of domain-add command (if you are migrating domain which is currently in use, please readAWS docs).
  2. you can provision certificate by specifying customCertificateArn and specifyingdisableDnsProvision
DomainConfiguration  API reference
Parent API reference: (HttpApiGateway or CdnConfiguration)
Required
domainName
Type: string

Fully qualified (absolute) domain name.

customCertificateArn
Type: string

ARN of a custom certificate to be provisioned with this domain

disableDnsProvision
Type: boolean

Disables creation of a 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
Type: boolean

Enables access logs

Default: JSON
format
Type: string ENUM

Configures format of the stored access logs

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

Cdn

CdnConfiguration  API reference
Parent API reference: HttpApiGateway
Required
enabled
Type: boolean
enables CDN distribution creation
cachingOptions
specifies custom caching options
forwardingOptions
specifies custom forwarding options
routeRewrites
Type: Array of CdnRouteRewrite
enables you to direct request for specified url paths to different origins
domainNames
Type: Array of DomainConfiguration
custom domain names for cdn distribution
cloudfrontPriceClass
Type: string ENUM
price class can be used to restrict the locations from which CDN serves traffic.
setResponseHeaders
Type: Array of CdnResponseHeader
manually set headers that CDN will automatically add to response
defaultRoutePrefix
Type: string
when used, cdn prefixes every request to the origin with the prefix
errorDocument
Type: string
custom error document url
indexDocument
Type: string
custom index (root) document for the distribution
Default: true
invalidateAfterDeploy
Type: boolean

if set to true, invalidates the cdn cache after each deploy

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:

  1. migrate domain with a help of domain-add command (if you are migrating domain which is currently in use, please readAWS docs).
  2. you can provision certificate by specifying customCertificateArn and specifyingdisableDnsProvision
DomainConfiguration  API reference
Parent API reference: CdnConfiguration
Required
domainName
Type: string

Fully qualified (absolute) domain name.

customCertificateArn
Type: string

ARN of a custom certificate to be provisioned with this domain

disableDnsProvision
Type: boolean

Disables creation of a 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 incoming requests to different origins: I.e., instead of forwarding a requests to the http-api-gateway, the request can be forwarded to the other origin (http-api-gateway, bucket or application-load-balancer).

CdnRouteRewrite  API reference
Parent API reference: CdnConfiguration
Required
path
Type: string

Path to be adjusted by this route rewrite

routePrefix
Type: string
when used, cdn route rewrite prefixes every request to the origin with the prefix
routeTo
determines origin to which this route rewrite forwards requests
setResponseHeaders
Type: Array of CdnResponseHeader
manually set headers that CDN will automatically add to response
cachingOptions
specifies custom caching options for the route rewrite
forwardingOptions
specifies custom forwarding options for the route rewrite

Routing to a bucket

CdnBucketRoute  API reference
Parent API reference: CdnRouteRewrite
Required
type
Type: string "bucket"
Type of the resource
Required
properties.bucketName
Type: string
name of the bucket
properties.disableUrlNormalization
Type: 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
Type: string "application-load-balancer"
Type of the resource
Required
properties.loadBalancerName
Type: string
name of the load balancer
Required
properties.listenerPort
Type: number
port of load balancer listener
properties.originDomainName
Type: 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
Type: string "http-api-gateway"
Type of the resource
Required
properties.httpApiGatewayName
Type: 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
Type: Array of string ENUM
only responses to specified methods will be cached
minTTL
Type: 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
Type: 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
Type: 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
Type: boolean
if enabled, CDN will automatically compress certain files returned from origin before returning to viewer
disableAcceptEncodingBrotli
Type: boolean
determines whether CDN can use Brotli compression
disableAcceptEncodingGzip
Type: boolean
determines whether CDN can use Gzip compression
cacheKeyParameters
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

The cache key section specifies which parts of a request are included in the cache key.

By default, requests are cached only based on the path.

A cache key can be configured to include headers, cookies, or query params.

CdnCacheKey  API reference
Parent API reference: CdnCachingOptions
cookies
specifies if and which cookies are included in cache key
headers
specifies if and which headers are included in cache key
queryString
specifies if and which query parameters are included in cache key

Cache key headers

CacheKeyHeaders  API reference
Parent API reference: CdnCacheKey
none
Type: boolean
if set to true, no headers are included in cache key
whitelist
Type: Array of string
only the headers listed are included in the cache key

Cache key cookies

CacheKeyCookies  API reference
Parent API reference: CdnCacheKey
none
Type: boolean
if set to true, no cookies are included in cache key
whitelist
Type: Array of string
only the cookies listed are included in the cache key
allExcept
Type: Array of string
all cookies except the ones listed are included in the cache key
all
Type: boolean
if set to true, all cookies are included in cache key

Cache key query string

CacheKeyQueryString  API reference
Parent API reference: CdnCacheKey
all
Type: boolean
if set to true, all query params are included in cache key
none
Type: boolean
if set to true, no query params are included in cache key
whitelist
Type: Array of string
only the query params listed are included in the cache key

Forwarding options

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

Different forwarding options can be specified for each route rewrite.

If no forwarding options are specified, Stacktape uses default forwarding options.

CdnForwardingOptions  API reference
Parent API reference: (CdnConfiguration or CdnRouteRewrite)
customRequestHeaders
Type: Array of CdnCustomRequestHeader
manually set headers which CDN will include when sending request to origin
allowedMethods
Type: Array of string ENUM
specifies which methods will be forwarded by CDN to the origin
cookies
specifies if and which cookies will be forwarded to the origin
headers
specifies if and which headers will be forwarded to the origin
queryString
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
Type: boolean
if set to true, no headers are forwarded to the origin
whitelist
Type: Array of string
only the headers listed are forwarded to the origin
allViewer
Type: boolean
if set to true, all viewer headers are forwarded to the origin
allViewerAndWhitelistCloudFront
Type: 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
Type: boolean
if set to true, no cookies are forwarded to the origin
whitelist
Type: Array of string
only the cookies listed are forwarded to the origin
all
Type: boolean
if set to true, all cookies are forwarded to the origin

Forwarding query string

ForwardQueryString  API reference
Parent API reference: CdnForwardingOptions
all
Type: boolean
if set to true, all query params are forwarded to the origin
none
Type: boolean
if set to true, no query params are forwarded to the origin
whitelist
Type: Array of string
only the query parameters listed are forwarded to the origin