HTTP API
Resource Overview
An HTTP API is used to define how users communicate with the resource that make up your serverless application. It represents an application programming interface (API) declared with Amazon API Gateway, a service that supports creation, deployment, and management of RESTful APIs. In a serverless architecture, an API Gateway API serves as an entry point for your backend.
Key Features of API Gateway include:
- Secure and deliberate access to resources
- Pay-as-you-go; Only pay for API calls you receive and the amount of data transferred out
- Authorization and access control, version management, and monitoring provided by AWS on your behalf
More specifically, an HTTP API allows you to declare a collection of API Gateway resources and methods that can be invoked through HTTPS endpoints. You're able to follow REST guidelines to add HTTP request methods and their respective paths as well as define a custom domain for users to access your API.
Event Subscription
Event subscription wires (solid line) visualize and configure event subscription integrations between two resources.
The following resources can be subscribed to HTTP API authorizers:
- User Pool Clients
The following resources can be subscribed to HTTP API routes:
- Function
Configurable Properties
Logical ID
The unique identifier used to reference this resource in the stack template. Defining a custom Logical ID is recommended, as it allows you to quickly identify a resource and any associated sub-resources when working with your stack in AWS, or anywhere outside of the Stackery Dashboard. As a project grows, it becomes useful in quickly spotting this resource in template.yaml or while viewing a stack in Template View mode.
The Logical ID of all sub-resources associated with this HTTP API will be prefixed with this value.
The identifier you provide must only contain alphanumeric characters (A-Za-z0-9) and be unique within the stack.
Default Logical ID Example: Api2
IMPORTANT : AWS uses the Logical ID of each resource to coordinate and apply updates to the stack when deployed. On any update of a resource's logical ID (or any modification that results in one), CloudFormation will delete the currently deployed resource and create a new one in it's place when the updated stack is deployed.
Authorizers
API Gateway Authorizers can be used to implement authorization for API routes. Authorizers grant access to requests which contain an OpenID token issued by a specific provider. Multiple Authorizers may be configured for an HTTP API. One can be used as the default authorizer for the API, while others can be used for individual routes.
This setting defines the number of Authorizers and provides a name for each. Authorizer configuration is performed separately, see Authorizer Settings below.
Routes
An HTTP API supports the following HTTP request methods:
- GET
- PUT
- POST
- DELETE
- HEAD
- ANY (Allows for any of the above methods)
Set CORS Allowed Origins
When this setting is enabled, API Gateway will add or override CORS Access-Control-Allow-Origin headers for all responses from the API.
CORS Allowed Origins
When Set CORS Allowed Origins is enabled, this setting provides the list of origins for the Access-Control-Allow-Origin response header.
Set CORS Allowed Headers
When this setting is enabled, API Gateway will add or override CORS Access-Control-Allow-Headers headers for all responses from the API.
CORS Allowed Headers
When Set CORS Allowed Headers is enabled, this setting provides a list of allowed headers for the Access-Control-Allow-Headers response header.
Set CORS Allowed Methods
When this setting is enabled, API Gateway will add or override CORS Access-Control-Allow-Methods headers for all responses from the API.
CORS Allowed Methods
When Set CORS Allowed Methods is enabled, this setting provides a list of exposed methods for the Access-Control-Allow-Methods response header.
Set CORS Exposed Headers
When this setting is enabled, API Gateway will add or override CORS Access-Control-Expose-Headers headers for all responses from the API.
CORS Exposed Headers
When Set CORS Exposed Headers is enabled, this setting provides a list of exposed headers for the Access-Control-Expose-Headers response header.
Set CORS Allow Credentials
When this setting is enabled, API Gateway will add or override CORS Access-Control-Allow-Credentials headers for all responses from the API.
CORS Allow Credentials
When Set CORS Allow Credentials is enabled, this setting sets the value of the Access-Control-Allow-Credentials response header.
Set CORS Max Age
When this setting is enabled, API Gateway will add or override CORS Access-Control-Max-Age headers for all responses from the API.
CORS Max Age
When Set CORS Max Age is enabled, this setting sets the value of the Access-Control-Max-Age response header.
Provision Custom Domain
By default, AWS automatically provisions a domain for you. When enabled, you're able to provide a custom domain to be used instead.
Custom Domain
The domain name that will host the API. AWS Certificate Manager will provision an SSL certificate for this domain. In order to provision the certificate, AWS will send an email to the domain's registration contacts and certain well-known domain administration email addresses:
- administrator@
- hostmaster@
- postmaster@
- webmaster@
- admin@
When deploying be sure to check these email addresses to approve the certificate. If the domain is not verified within one hour of the start of the deployment the deployment will fail and be rolled back automatically.
After deployment a CNAME DNS record will need to be created for the domain. Select the current deployment in the Stackery dashboard, then select the HTTP API on the Stackery Dashboard. Find and copy the DNS Name value in the properties panel on the right. Create a CNAME record to map the custom domain to this DNS name. Check with your DNS provider for instructions on how to create the record.
When using a custom domain, the Validation Domain field is required, and should be filled in with the top-level domain (i.e. if your domain is api.myapp.com, the validation domain would be myapp.com).
Authorizer
An Authorizer can be configured by connecting it to a User Pool Client or by providing details directly in the Authorizer settings. To edit the Authorizer settings, double-click on the Authorizer to configure the following properties:
Identity Source
The Identity Source is the expected location of the OpenID authorization token in the HTTP request. The default value of $request.header.Authorization expects the token to be present in the Authorization HTTP header. See the AWS API Gateway Documentation for details on possible values.
JWT Issuer
API Gateway supports JWT formatted OpenID tokens. The JWT format encodes each token's JWT Issuer in the token's iss property. This setting specifies the expected value of the JWT Issuer in authorized tokens.
This setting will be automatically configured when you connect an Authorizer to a User Pool Client.
JWT Audience
API Gateway supports JWT formatted OpenID tokens. The JWT format encodes each token's JWT Audience in the token's aud property. This setting specifies allowed values of the JWT Audience in authorized tokens.
This setting will be automatically configured when you connect an Authorizer to a User Pool Client.
OpenID Connect URL
An OpenID Connect service may publish a URL used to discover token issuer information. Providing this optional OpenID Connect URL enables further dynamic token issuer discovery where available.
Authorization Scopes
API Gateway supports JWT formatted OpenID tokens. The JWT format encodes each token's Authorization Scopes in the token's scopes property. This setting specifies allowed values of the Authorization Scopes in authorized tokens.
Route
Double-click on the Route to configure the following properties:
Proxy To Existing HTTP Service
Check this box to proxy requests to this route to an existing API.
Routes may either proxy to an existing HTTP service or be connected to a Function. Enabling this setting will remove an existing event subscription to a Function.
HTTP Service Location
After enabling the Proxy to existing HTTP service setting, this setting provides the location of the existing API to route requests to.
If the route contains a wildcard "proxy" path variable, the variable can also be used for dynamic routing to the existing API. For example, a route's Path may be /users/{proxy+} with its HTTP Service Location set to https://abc.example.com/v1/users/{proxy}. This will cause a request to this API's /users/5/details.json path to be proxied to https://abc.example.com/v1/users/5/details.json.
IAM Permissions
When connected by a service discovery wire (dashed wire), a Function or Docker Task will add the following IAM policy to its role and gain permission to access this resource.
No Permissions Added
Environment Variables
When connected by a service discovery wire (dashed wire), a Function or Docker Task will automatically populate and reference the following environment variables in order to interact with this resource.
API_URL
The base URL used to access the API.
Example: https://a2t4in91ie.execute-api.us-west-2.amazonaws.com
Metrics & Logs
Double clicking a resource while viewing your stack's current deployment gives you access to your pre-configured resource properties, and links to the following metrics and logs.
- Response Metrics
- Response Time
Related AWS Documentation
AWS Documentation: AWS::Serverless::HttpApi