Overview

• HTTP API gateways represent entry-points to your application from an outer internet. They route traffic to your application and integrate easily with compute resources of your stack: functions, batch-jobs or multi-container-workloads.
• HTTP API gateways are used to communicate with your compute resources 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 compute resources 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 parameters, ip address or HTTP headers in the request.

Basic usage

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

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

Integrating with compute resources

By creating event integration on a workload(multi-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 compute resource (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 multi-container-workload docs.

Following example shows:

• integration attached to mySingleContainer which forwards all requests (greedy path /{proxy+} and ANY method *) to the multi-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: 'multi-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

More information on integrating compute resources with HTTP API can be found:

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

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 communicating 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 single line.

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

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

Custom domain names

If you do not have a custom domain and want one, read the section Registering domain on the Domains and TLS certificates page.

If you already have an existing domain and you wish to use it with your app, there are two approaches:

1. Using Stacktape to manage domains and certs - you must use Route53 in your AWS account as your DNS.
2. Using 3rd party DNS provider - such as GoDaddy, Cloudflare etc. You must handle domains and generate certificates yourself.

For more information about domain management options, refer to Domains and TLS certificates page.

Using Stacktape to manage domains and certs

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

Using 3rd party DNS

To use 3rd party provider follow these steps:

1. Create/import a custom TLS certificate for your domain in AWS console. Copy certificate ARN; you will need it in the next step.
2. After the certificate is validated (Issued), assign your domain to your resource:
   • use the ARN of your certificate as customCertificateArn
   • disable DNS record creation (because you are using third party DNS)

Copy
resources:
  myWebsite:
    type: http-api-gateway
    properties:
      customDomains:
        - domainName: mydomain.com
          disableDnsRecordCreation: true
          customCertificateArn: <<ARN_OF_YOUR_CERTIFICATE>>

3. After you deploy your API gateway, you can find the domain name in Stacktape console in:

   Your project and stage > Click on your API Gateway resource to see its domain

   Once you have the domain name, you can point DNS record to this domain using your DNS provider:

   • Use ALIAS record type for root domains (i.e mydomain.com)
   • Use CNAME record type for subdomains (i.e www.mydomain.com or staging.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.

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

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.

For information about using CDN refer to our CDN docs.

Referenceable parameters