Stacktape

Sign up



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, application load balancers also support routing based on query paramters, ip address or HTTP headers in the request.

Basic usage

HttpApiGateway  API reference
type
Required
properties.payloadFormat
properties.cors
properties.logging
properties.customDomains
properties.cdn
overrides

By default http-api-gateway does not need to have any properties defined.

Copy

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

Integrating with workloads

By creating event integration on a workload(container-workload, function, batch-job), you are telling http-api-gateway to forward requests to the workload.

Each integration must specify:

  • httpApiGatewayName - name of the http-api-gateway that will forward requests to the integration
  • path
    • path pattern that a request must match to be forwarded to the workload (wildcards and greedy paths possible).
    • if multiple integrations match the request, http-api-gateway selects the most specific match.
  • method - method of the request (GET, POST, DELETE, etc.) that a request must match to be forwarded to the workload
  • for more information see function or container-workload docs.

Following example shows:

  • integration attached to mySingleContainer which forwards all requests (greedy path /{proxy+} and ANY method *) to the container-workload.
  • integration attached to myFunction which forwards requests with URL path /invoke-my-function and method GET to the function.
  • since the integration on myFunction is more specific than the integration on mySingleContainer: if a GET /invoke-my-function request comes, myFunction integration is proritized.

Copy

resources:
myHttpApi:
type: http-api-gateway
myFunction:
type: function
properties:
packaging:
type: stacktape-lambda-buildpack
properties:
entryfilePath: 'path/to/my-lambda.ts'
events:
- type: http-api-gateway
properties:
httpApiGatewayName: 'myHttpApi'
path: '/invoke-my-function'
method: 'GET'
mySingleContainer:
type: 'container-workload'
properties:
containers:
- name: 'myAppContainer'
packaging:
type: stacktape-image-buildpack
properties:
entryfilePath: '_example-configs/containers/ts-container.ts'
environment:
- name: port
value: 80
events:
- type: 'http-api-gateway'
properties:
httpApiGatewayName: 'myHttpApi'
containerPort: 80
path: /{proxy+} # greedy path
method: '*'
resources:
cpu: 0.25
memory: 512

HTTP API gateway with function and container-workload integrations.

More information on integrating workloads with HTTP API can be found:

CORS

Cross-origin resource sharing (CORS) is a browser security feature that restricts cross-origin HTTP requests that are initiated from scripts running in the browser.

A cross-origin HTTP request is a request that is made to a different domain or a different subdomain than the one browser is currently on.


Example: If your website has domain mydomain.com and it communicates with your http-api-gateway which has domain api.mydomain.com then the browser must perform cross origin request when communcating with this http-api-gateway.


There are two types of cross-origin requests:

  1. Simple requests

    • requests that do not require CORS preflight.
    • To understand what is considered a simple request refer to Mozilla docs.
    • You do not need to configure CORS on your gateway for these types of requests. However, responses from your application should still include Access-Control-Allow-Origin header where the value of the header key is set to *(any origin) or is set to the origins allowed to access that resource. Refer to Mozilla docs for more information.
  2. NON-simple (preflighted) requests

    • all cross origin requests that are not considered simple are NON-simple and require preflight requests.
    • If you send NON-simple CORS requests from browser to your API, you need to enable CORS which takes care of preflight requests.

If you need to use NON-simple cross origin requests you need to enable CORS. CORS can be enabled with a signle line.

Copy

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

http-api-gateway with CORS enabled

You can additionally configure CORS headers by setting properties in cors configuration.

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

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

Custom domain names

Stacktape allows you to connect your custom domain names to some of your resources (HTTP API Gateways, Application Load Balancers and Buckets with CDNs).

Connecting a custom domain to the resource does 2 things:

  • Creates DNS records:
    • If you use your custom domain with a resource, Stacktape automatically creates a DNS record (during deploy) pointing the specified domain name to the resource.
  • Adds TLS certificates
    • If the origin resource (HTTP API Gateway, Application Load Balancer or CDN) uses HTTPS protocol, Stacktape takes care of issuing and attaching correct (free, AWS-managed) certificate to the resource. This means, you do not have to deal with TLS termination as it is handled by the connected resource.
    • If you want to use your own certificates, you can configure customCertificateArns.

To manage a custom domain, it first needs to be added to your AWS account. This means that a hosted zone (collection of records managed together for a given domain) for your domain exists in your AWS account and your domain registrar's name servers are pointing to it. To learn more, refer to Adding a domain guide.

DomainConfiguration  API reference
Parent API reference: (HttpApiGateway or CdnConfiguration)
domainName
Required
customCertificateArn
disableDnsRecordCreation

Copy

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

Access logs

Access logs contain basic information about requests coming to your http-api-gateway. They can be useful in case of audit and are many times needed for compliance reasons.

  • 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

Stacktape enables access logging by default, with retention time set to 30 days.

HttpApiAccessLogsConfig  API reference
Parent API reference: HttpApiGateway
disabled
format
Default: JSON
retentionDays
Default: 30

Copy

resources:
myHttpApi:
type: 'http-api-gateway'
properties:
logging:
format: CSV

CDN

You can configure AWS Cloudfront CDN (Content Delivery Network) to be in front of your http-api-gateway.

  • CDN is a globally distributed network that can cache responses 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
    • improve security
  • The "origin" is the resource (HTTP API Gateway) to which CDN is attached. 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.

For information about using CDN refer to our CDN docs.

Referenceable parameters

The following parameters can be easily referenced using $ResourceParam directive directive.

To learn more about referencing parameters, refer to referencing parameters.

domain
  • Default domain name

  • Usage: $ResourceParam('<<resource-name>>', 'domain')
url
  • Default URL

  • Usage: $ResourceParam('<<resource-name>>', 'url')
customDomains
  • Comma-separated list of custom domain names assigned to the HTTP Api Gateway (only available if you use custom domain names)

  • Usage: $ResourceParam('<<resource-name>>', 'customDomains')
customDomainUrls
  • Comma-separated list of custom domain name URLs (only available if you use custom domain names)

  • Usage: $ResourceParam('<<resource-name>>', 'customDomainUrls')
cdnDomain
  • Default domain of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).

  • Usage: $ResourceParam('<<resource-name>>', 'cdnDomain')
cdnUrl
  • Default url of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).

  • Usage: $ResourceParam('<<resource-name>>', 'cdnUrl')
cdnCustomDomains
  • Comma-separated list of custom domain names assigned to the CDN (only available if you configure custom domain names for the CDN).

  • Usage: $ResourceParam('<<resource-name>>', 'cdnCustomDomains')
cdnCustomDomainUrls
  • Comma-separated list of custom domain name URLs of the CDN (only available if you configure custom domain names for the CDN).

  • Usage: $ResourceParam('<<resource-name>>', 'cdnCustomDomainUrls')
Need help? Ask a question on SlackDiscord or info@stacktape.com.