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 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
accessLogs
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
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:

  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
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
specifies custom caching options
forwardingOptions
specifies custom forwarding options
routeRewrites
Array of CdnRouteRewrite
enables you to direct request for specified url paths to different origins
domainNames
custom domain names for cdn distribution
cloudfrontPriceClass
string ENUM
price class can be used to restrict the locations from which CDN serves traffic.
setResponseHeaders
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:

  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
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
determines origin to which this route rewrite forwards requests
setResponseHeaders
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 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
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
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
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
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
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
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