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
No description
Type: string "http-api-gateway"
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
Configures CORS (Cross-Origin Resource Sharing) HTTP headers for this HTTP API Gateway.
Type: HttpApiCorsConfig
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
andresponseLength
. - You can configure log format. Supported values are
CLF
,JSON
,XML
andCSV
. - 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
- go to the log group page in the AWS CloudWatch console. You can use
Attaches a custom domains to this HTTP API Gateway
Type: Array of DomainConfiguration
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.
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 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.
Overrides one or more properties of the specified child resource.
Type: Object
- Child resources are specified using their cloudformation logical id (e.g.
MyBucketBucket
). - 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 overridden, refer to AWS Cloudformation docs.
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 integrationpath
- 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 methodGET
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-gatewaymyFunction:type: functionproperties:packaging:type: stacktape-lambda-buildpackproperties:entryfilePath: 'path/to/my-lambda.ts'events:- type: http-api-gatewayproperties:httpApiGatewayName: 'myHttpApi'path: '/invoke-my-function'method: 'GET'mySingleContainer:type: 'container-workload'properties:containers:- name: 'myAppContainer'packaging:type: stacktape-image-buildpackproperties:entryfilePath: '_example-configs/containers/ts-container.ts'environment:- name: portvalue: 80events:- type: 'http-api-gateway'properties:httpApiGatewayName: 'myHttpApi'containerPort: 80path: /{proxy+} # greedy pathmethod: '*'resources:cpu: 0.25memory: 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:
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.
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 gatewayAllowedOrigins
:*
AllowedHeaders
:Content-Type
,X-Amz-Date
,Authorization
,X-Api-Key
,X-Amz-Security-Token
,X-Amz-User-Agent
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 integrations associated with the api gatewayAllowedOrigins
:*
AllowedHeaders
:Content-Type
,X-Amz-Date
,Authorization
,X-Api-Key
,X-Amz-Security-Token
,X-Amz-User-Agent
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
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.
Allowed HTTP methods
Type: Array of string ENUM
Possible values: *DELETEGETHEADOPTIONSPATCHPOSTPUT
Configures the presence of credentials in the CORS request
Type: boolean
Response headers that should be made available to scripts running in the browser, in response to a cross-origin request
Type: Array of string
Time in seconds that browser can cache the response for a preflight request
Type: number
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.
Fully qualified (absolute) domain name.
Type: string
- Must be specified WITHOUT the protocol (omit the https:// part)
- Example:
mydomain.com
orpreview.mydomain.com
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).
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
true
.
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
andresponseLength
. - You can configure log format. Supported values are
CLF
,JSON
,XML
andCSV
. - 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
- go to the log group page in the AWS CloudWatch console. You can use
Stacktape enables access logging by default, with retention time set to 30 days.
Disables the collection of access logs to CloudWatch
Type: boolean
Configures format of the stored access logs
Type: string ENUM
Possible values: CLFCSVJSONXML
- Stored properties are:
requestId
,ip
,requestTime
,httpMethod
,routeKey
,status
,protocol
andresponseLength
.
Amount of days the logs will be retained in the log group
Type: number ENUM
Possible values: 13571430609012015018036540054573118273653
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.
Default domain name
- Usage:
$ResourceParam('<<resource-name>>', 'domain')
Default URL
- Usage:
$ResourceParam('<<resource-name>>', 'url')
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')
Comma-separated list of custom domain name URLs (only available if you use custom domain names)
- Usage:
$ResourceParam('<<resource-name>>', 'customDomainUrls')
Default domain of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnDomain')
Default url of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnUrl')
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')
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')