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

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:

• integrate functions with HTTP API gateway.
• integrate container-workloads with HTTP API gateway.

Cors

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

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

Access logs

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

Cdn

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

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

Routing to a bucket

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

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

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.

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.

Cache key headers

Cache key cookies

Cache key query 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.

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

resources:
  myHttpApi:
    type: 'http-api-gateway'
    properties:
      cdn:
        enabled: true
        forwardingOptions:
          allowedMethods:
            - 'GET'
            - 'POST'

API reference