logoStacktape docs




Http Api Gateways

Overview and basic concepts

  • 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
type
Required

No description

Type: string "http-api-gateway"

properties.payloadFormat

Determines the shape of the event delivered to your integrations.

Type: string ENUM

Possible values: 1.02.0

  • Payload can be also set on the integration level (when configuring events for your workload). This value is only used if the payload format is not set on the integration level.
  • To understand differences between payload formats, refer to AWS Docs

properties.logging

Configures logging of the requests coming to the HTTP Api Gateway (access logs)

Type: HttpApiAccessLogsConfig

  • Stored properties are: requestId, ip, requestTime, httpMethod, routeKey, status, protocol and responseLength.
  • You can configure log format. Supported values are CLF, JSON, XML and CSV.
  • You can browse your logs in 2 ways:
    • go to the log group page in the AWS CloudWatch console. You can use stacktape stack-info command to get a direct link.
    • use stacktape logs command to print logs to the console

properties.customDomains

Configures domain names attached to this Http Api Gateway

Type: Array of DomainConfiguration

properties.cdn

Configures AWS Cloudfront CDN (Content Delivery Network) to be in front of your HTTP API Gateway

Type: CdnConfiguration

  • CDN is a globally distributed network that can cache reponses from your HTTP API Gateway at the edge - close to your users.
  • AWS Cloudfront has 205 edge locations on 6 continents.
  • The CDN is used to:
    • reduce latency & improve load times
    • reduce bandwidth costs
    • reduce the amount of traffic coming to the origin
  • The "origin" is the resource connected to the CDN. CDN caches responses from the origin at the edge for specified amount of time.
  • If the content requested by the client is in the CDN cache, the CDN immediately returns it to the client without making a request to the origin.
  • If the content is NOT in the cache, the CDN makes a request to the Origin. The response from the origin is then forwarded to the client, and cached at the edge.

overrides

Overrides one or more properties of the specified child resource.

Type: Object

  • Child resouces are specified using their descriptive name (e.g. DbInstance or Events.0.HttpApiRoute).
  • To see all configurable child resources for given Stacktape resource, use stacktape stack-info --detailed command.
  • To see the list of properties that can be overriden, refer to AWS Cloudformation docs.

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
enabled
Required

Enables CORS (Cross-Origin Resource Sharing)

Type: boolean

If you do not specify any additional properties, default CORS configuration is used:

  • AllowedMethods: Inferred from methods used by the integration
  • AllowedOrigins: *
  • AllowedHeaders: Content-Type, X-Amz-Date, Authorization, X-Api-Key, X-Amz-Security-Token, X-Amz-User-Agent

allowedOrigins

Origins to accepts cross-domain requests from

Type: Array of string

  • Origin is a combination of scheme (protocol), hostname (domain), and port of the URL
  • Examples of same origin: http://example.com/app1:80 http://example.com/app2
  • Examples of a different origin: http://example.com/app1 https://example.com/app2

allowedHeaders

Allowed HTTP headers

Type: Array of string

  • Each header name in the Access-Control-Request-Headers header of a preflight request must match a corresponding entry in the rule.

allowedMethods

Allowed HTTP methods

Type: Array of string ENUM

Possible values: *DELETEGETHEADOPTIONSPATCHPOSTPUT

allowCredentials

Configures the presence of credentials in the CORS request

Type: boolean

exposedResponseHeaders

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

Type: Array of string

maxAge

Time in seconds that browser can cache the response for a preflight request

Type: number

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)
domainName
Required

Fully qualified (absolute) domain name.

Type: string

customCertificateArn

ARN of a custom certificate to be provisioned with this domain

Type: string

  • Stacktape generates certificates for all your domains.
  • If you want to use a custom certificate (managed within your AWS account), you can specify its ARN (Amazon Resource Name).

disableDnsRecordCreation
Default: true

Enables creation of a DNS record

Type: boolean

  • Stacktape creates a DNS record by default for all of your domains.
  • If you want to configure DNS records on your own, set this to false.

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

Access logs

HttpApiAccessLogsConfig  API reference
Parent API reference: HttpApiGateway
enabled

Enables logging

Type: boolean

format
Default: JSON

Configures format of the stored access logs

Type: string ENUM

Possible values: CLFCSVJSONXML

  • Stored properties are: requestId, ip, requestTime, httpMethod, routeKey, status, protocol and responseLength.

retentionDays
Default: 30

Amount of days the logs will be retained in the log group

Type: number ENUM

Possible values: 13571430609012015018036540054573118273653

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

Cdn

CdnConfiguration  API reference
Parent API reference: HttpApiGateway
enabled
Required

Enables the CDN

Type: boolean

cachingOptions

Configures custom caching options

Type: CdnCachingOptions

  • Configures the caching behavior of your edge distribution (what & when should stay in cache, and when to refetch it from the origion)

forwardingOptions

Configures which parts of the request are forwarded to the origin (headers, query parameters, cookies etc.)

Type: CdnForwardingOptions

routeRewrites

Enables you to redirect specific requests to a different origin

Type: Array of CdnRouteRewrite

  • Each incoming request to the CDN is first evaluated against route rewrites. The requested path is compared with path pattern specified in route rewrite.
  • If the requested path matches the path pattern specified by route rewrite, the request is sent to the configured route.
  • Route rewrites are evaluated in order. The first match is where the request will be sent to.
  • If no match is found, request is sent to the default origin (the one that the CDN is attached to).

Example use cases:

  • Most of the content you are serving is a static content served from a bucket (static website). Some content however needs to be rendered dynamically by a lambda function. You can route paths that need to be rendered dynamically to the lambda function through http-api-gateway.
  • You want to cache your jpg files longer than other files. You can create route rewrite that will catch every path ending with jpg and set custom caching options for these paths.

customDomains

Custom domain names to connect to this CDN distribution

Type: Array of DomainConfiguration

cloudfrontPriceClass
Default: 'PriceClass_All'

Configures locations from which the CDN serves traffic

Type: string ENUM

Possible values: PriceClass_100PriceClass_200PriceClass_All

  • Higher price class results in more locations that serve your traffic.
  • This can result in better performance, but is more costly.
  • Example: If your users are located only in US & Europe, you can save money by configuring PriceClass_100
  • To learn more about price classes, refer to AWS docs

defaultRoutePrefix

Prefixes requests to the origin with specified prefix

Type: string

  • Example: If the CDN receives a request with path /my/resource/url, the request will be sent to the origin as <>/my/resource/url

errorDocument

Custom error document URL

Type: string

  • Error document is requested by the CDN if the original request to the origin responds with an error code 403, 404 or 500.
  • Example: /error.html

indexDocument
Default: '/index.html'

Custom index (root) document served for requests with path /

Type: string

invalidateAfterDeploy
Default: true

Invalidates the CDN cache after each deployment

Type: boolean

  • This prevents serving outdated content to your users
  • If you choose to invalidate the cache, CDN will flush all the cached content and new requests will result in a request to the origin (bucket, application-load-balancer or http-api-gateway)

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
domainName
Required

Fully qualified (absolute) domain name.

Type: string

customCertificateArn

ARN of a custom certificate to be provisioned with this domain

Type: string

  • Stacktape generates certificates for all your domains.
  • If you want to use a custom certificate (managed within your AWS account), you can specify its ARN (Amazon Resource Name).

disableDnsRecordCreation
Default: true

Enables creation of a DNS record

Type: boolean

  • Stacktape creates a DNS record by default for all of your domains.
  • If you want to configure DNS records on your own, set this to false.

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
path
Required

Path to be adjusted by this route rewrite

Type: string

  • You can use wildcards for your path patterns to match multiple paths.
  • To learn more about path patterns, refer to AWS docs

routePrefix

Prefixes every request to the origin with the specified prefix

Type: string

  • Example: If the CDN receives a request with path /my/resource/url, the request will be sent to the origin as <>/my/resource/url

routeTo

Configures the origin to which the route rewrite forwards requests

Type: (CdnLoadBalancerRoute or CdnHttpApiGatewayRoute or CdnBucketRoute)

  • If not set, the default origin (the one this CDN is attached to) is used

cachingOptions

Configuires custom caching options for this route rewrite

Type: CdnCachingOptions

  • Configures the caching behavior of your edge distribution (what & when should stay in cache, and when to refetch it from the origion)

forwardingOptions

Enables you to redirect specific requests to a different origin

Type: CdnForwardingOptions

  • Forwarding options enable you to set which parts of the request are forwarded to the origin (headers, query params, cookies etc.)

Routing to a bucket

CdnBucketRoute  API reference
Parent API reference: CdnRouteRewrite
type
Required

No description

Type: string "bucket"

properties.bucketName
Required

Name of the bucket

Type: string

properties.disableUrlNormalization
Default: true

Disables URL normalization (ability to use clean urls without the .html extension)

Type: boolean

  • URL normalization is enabled by default.
  • URL normalization is useful when you want to serve HTML files from the bucket
  • When the URL normalization is enabled, the CDN is able to fetch correct HTML files from the bucket even when incomplete URL is used (without the .html extension)
  • This enables you to use URLs such as <>/about instead of urls <>/about.html or <>/about/index.html

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
type
Required

No description

Type: string "application-load-balancer"

properties.loadBalancerName
Required

Name of the Load balancer

Type: string

properties.listenerPort
Required

Port of the Load balancer listener

Type: number

properties.originDomainName

Explicitly sets the origin domain name you wish to use when forwarding to load balancer

Type: string

  • This is only neccessary if the load balancer has no customDomains attached and listener uses customCertificateArns

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
type
Required

No description

Type: string "http-api-gateway"

properties.httpApiGatewayName
Required

Name of the HTTP Api Gateway

Type: string

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

Only responses to the requests with these methods will be cached

Type: Array of string ENUM

Possible values: GETHEADOPTIONS

  • Possible values are:
    • ['GET', 'HEAD']
    • ['GET', 'HEAD', 'OPTIONS']

minTTL

The minimum amount of time in seconds that the objects will stay in the CDN cache before another request is sent to the origin

Type: number

  • To learn more about cache expiration, refer to AWS Docs

maxTTL

The maximum amount of time in seconds that the objects will stay in the CDN cache before another request is sent to the origin

Type: number

  • To learn more about cache expiration, refer to AWS Docs

defaultTTL

The default amount of time in seconds that the objects will stay in the CDN cache before another request is sent to the origin

Type: number

  • To learn more about cache expiration, refer to AWS Docs

disableCompression
Default: false

Disables compression of the objects served by the CDN

Type: boolean

  • Compression is enabled by default.
  • Compression can significantly reduce the size of the responses from the CDN. In some cases, less than a quarter the size of the original. This can result in a better performance and lower transfer costs.
  • The CDN compresses objects using the Gzip and Brotli compression methods.
  • If the viewer supports both formats, Brotli version is used.
  • The client must indicate that it acceps compressed files using the Accept-Encoding HTTP header.
  • To learn more about compression, refer to AWS Docs

cacheKeyParameters

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

Type: CdnCacheKey

  • The values included in the cache key are automatically forwarded in the requests that the CDN sends to the origin.

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

Configures cookies that will be included in the cache key

Type: CacheKeyCookies

  • The cookies included in the cache key are automatically forwarded in the requests that the CDN sends to the origin.
  • By default no cookies are included in the cache key.

headers

Configures headers that will be included included in the cache key

Type: CacheKeyHeaders

  • The headers included in the cache key are automatically forwarded in the requests that the CDN sends to the origin.
  • By default no headers (except Accept-Encoding for compression to work) are included in the cache key.

queryString

Configures query parameters that will be included in the cache key

Type: CacheKeyQueryString

  • The query params included in the cache key are automatically forwarded in the requests that the CDN sends to the origin.
  • By default no query params are included in the cache key.

Cache key headers

CacheKeyHeaders  API reference
Parent API reference: CdnCacheKey
none

No headers are included in the cache key

Type: boolean

whitelist

Only the headers listed are included in the cache key

Type: Array of string

Cache key cookies

CacheKeyCookies  API reference
Parent API reference: CdnCacheKey
none

No cookies are included in the cache key

Type: boolean

whitelist

Only the listed cookies are included in the cache key

Type: Array of string

allExcept

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

Type: Array of string

all

All cookies are included in the cache key

Type: boolean

Cache key query string

CacheKeyQueryString  API reference
Parent API reference: CdnCacheKey
all

All query params are included in the cache key

Type: boolean

none

No query params are included in the cache key

Type: boolean

whitelist

Only the query parameters listed are included in the cache key

Type: Array of string

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

Adds static headers that the CDN will add to all requests sent to the origin

Type: Array of CdnCustomRequestHeader

allowedMethods

Configured methods that will be forwarded by the CDN to the origin

Type: Array of string ENUM

Possible values: DELETEGETHEADOPTIONSPATCHPOSTPUT

  • If not set, all methods are forwarded

cookies

Configured cookies forwarded to the origin

Type: ForwardCookies

  • If not set, all cookies are forwarded
  • All cookies that are part of the cache key (see cachingOptions) are automatically forwarded to the origin.

headers

Configured headers will be forwarded to the origin

Type: ForwardHeaders

  • If not set, all headers are forwarded
  • All headers that are part of the cache key (see cachingOptions) are automatically forwarded to the origin.

queryString

Configured query params will be forwarded to the origin

Type: ForwardQueryString

  • If not set, all query string parameters are forwarded
  • All query string parameters that are part of the cache key (see cachingOptions) are automatically 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

No headers are forwarded to the origin

Type: boolean

whitelist

Only the headers listed are forwarded to the origin

Type: Array of string

allViewer

All viewer headers are forwarded to the origin

Type: boolean

allViewerAndWhitelistCloudFront

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

Type: Array of string

Forwarding cookies

ForwardCookies  API reference
Parent API reference: CdnForwardingOptions
none

No cookies are forwarded to the origin

Type: boolean

whitelist

Only the cookies listed are forwarded to the origin

Type: Array of string

all

All cookies are forwarded to the origin

Type: boolean

Forwarding query string

ForwardQueryString  API reference
Parent API reference: CdnForwardingOptions
all

All query params are forwarded to the origin

Type: boolean

none

No query params are forwarded to the origin

Type: boolean

whitelist

Only the query parameters listed are forwarded to the origin

Type: Array of string

API reference

CdnCustomRequestHeader  API reference
Parent API reference: CdnForwardingOptions
headerName
Required

Name of the header

Type: string

value
Required

Value of the header

Type: string