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

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

YML
Typescript
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.

YML
Typescript
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

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

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.

YML
Typescript
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

YML
Typescript
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.

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

YML
Typescript
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