ApiGatewayV2
Reference doc for the `sst.aws.ApiGatewayV2` component.
The ApiGatewayV2
component lets you add an Amazon API Gateway HTTP API to your app.
Create the API
Add a custom domain
Add routes
Configure the routes
You can configure the route and its handler function.
Set defaults for all routes
You can use the transform
to set some defaults for all your routes. For example,
instead of setting the memory
for each route.
You can set it through the transform
.
Constructor
Parameters
-
name
string
-
args?
ApiGatewayV2Args
-
opts?
ComponentResourceOptions
ApiGatewayV2Args
accessLog?
Type Input
<
Object
>
Default {retention: “forever”}
Configure the API Gateway logs in CloudWatch. By default, access logs are enabled and kept forever.
accessLog.retention?
Type Input
<
“
1 day
”
|
“
3 days
”
|
“
5 days
”
|
“
1 week
”
|
“
2 weeks
”
|
“
1 month
”
|
“
2 months
”
|
“
3 months
”
|
“
4 months
”
|
“
5 months
”
|
“
6 months
”
|
“
1 year
”
|
“
13 months
”
|
“
18 months
”
|
“
2 years
”
|
“
3 years
”
|
“
5 years
”
|
“
6 years
”
|
“
7 years
”
|
“
8 years
”
|
“
9 years
”
|
“
10 years
”
|
“
forever
”
>
Default forever
The duration the API Gateway logs are kept in CloudWatch.
domain?
Type Input
<
string
|
Object
>
Set a custom domain for your HTTP API.
Automatically manages domains hosted on AWS Route 53, Cloudflare, and Vercel. For other
providers, you’ll need to pass in a cert
that validates domain ownership and add the
DNS records.
By default this assumes the domain is hosted on Route 53.
For domains hosted on Cloudflare.
domain.cert?
Type Input
<
string
>
The ARN of an ACM (AWS Certificate Manager) certificate that proves ownership of the domain. By default, a certificate is created and validated automatically.
To manually set up a domain on an unsupported provider, you’ll need to:
- Validate that you own the domain by creating an ACM certificate. You can either validate it by setting a DNS record or by verifying an email sent to the domain owner.
- Once validated, set the certificate ARN as the
cert
and setdns
tofalse
. - Add the DNS records in your provider to point to the API Gateway URL.
domain.dns?
Type Input
<
false
|
sst.aws.dns
|
sst.cloudflare.dns
|
sst.vercel.dns
>
Default sst.aws.dns
The DNS provider to use for the domain. Defaults to the AWS.
Takes an adapter that can create the DNS records on the provider. This can automate validating the domain and setting up the DNS routing.
Supports Route 53, Cloudflare, and Vercel adapters. For other providers, you’ll need
to set dns
to false
and pass in a certificate validating ownership via cert
.
Specify the hosted zone ID for the Route 53 domain.
Use a domain hosted on Cloudflare, needs the Cloudflare provider.
Use a domain hosted on Vercel, needs the Vercel provider.
domain.name
Type Input
<
string
>
The custom domain you want to use.
Can also include subdomains based on the current stage.
domain.path?
Type Input
<
string
>
The base mapping for the custom domain. This adds a suffix to the URL of the API.
Given the following base path and domain name.
The full URL of the API will be https://api.example.com/v1/
.
Be default there is no base path, so if the name
is api.example.com
, the full URL will be https://api.example.com
.
transform?
transform.accessLog?
Type LogGroupArgs
|
(
args
:
LogGroupArgs
=>
void
)
Transform the CloudWatch LogGroup resource used for access logs.
transform.api?
transform.domainName?
Type DomainNameArgs
|
(
args
:
DomainNameArgs
=>
void
)
Transform the API Gateway HTTP API domain name resource.
transform.route?
Type Object
Transform the routes. This is called for every route that is added.
You can use this to set any common props for all the routes and their handler function. Like the other transforms, you can either pass in an object or a callback.
Here we are ensuring that all handler functions of our routes have a memory of 2048 MB
.
Enable IAM auth for all our routes.
transform.route.args?
Type ApiGatewayV2RouteArgs
|
(
args
:
ApiGatewayV2RouteArgs
=>
void
)
Transform the arguments for the route.
transform.route.handler?
Type FunctionArgs
|
(
args
:
FunctionArgs
=>
void
)
Transform the handler function of the route.
transform.stage?
Properties
nodes
nodes.api
Type Api
The Amazon API Gateway HTTP API
nodes.logGroup
Type LogGroup
The CloudWatch LogGroup for the access logs.
url
Type Output
<
string
>
The URL of the API.
If the domain
is set, this is the URL with the custom domain.
Otherwise, it’s the autogenerated API Gateway URL.
SDK
The following are accessible through the SDK at runtime.
url
Type string
The URL of the API.
If the domain
is set, this is the URL with the custom domain.
Otherwise, it’s the autogenerated API Gateway URL.
Methods
route
Parameters
The path for the route.route
string
The function that’ll be invoked.handler
string
|
FunctionArgs
Configure the route.args?
ApiGatewayV2RouteArgs
Returns ApiGatewayV2LambdaRoute
Add a route to the API Gateway HTTP API. The route is a combination of
- An HTTP method and a path,
{METHOD} /{path}
. - Or a
$default
route.
A method could be one of GET
, POST
, PUT
, DELETE
, PATCH
, HEAD
, OPTIONS
, or ANY
. Here ANY
matches any HTTP method.
The path can be a combination of
- Literal segments,
/notes
,/notes/new
, etc. - Parameter segments,
/notes/{noteId}
,/notes/{noteId}/attachments/{attachmentId}
, etc. - Greedy segments,
/{proxy+}
,/notes/{proxy+}
, etc. The{proxy+}
segment is a greedy segment that matches all child paths. It needs to be at the end of the path.
The $default
is a reserved keyword for the default route. It’ll be matched if no other route matches.
When a request comes in, the API Gateway will look for the most specific match. If no route matches, the $default
route will be invoked.
Here’s how you add a simple route.
Match any HTTP method.
Add a default route.
Add a parameterized route.
Add a greedy route.
Enable auth for a route.
Customize the route handler.
ApiGatewayV2RouteArgs
auth?
Type Input
<
Object
>
Enable auth for your HTTP API.
auth.iam?
Type Input
<
true
>
Enable IAM authorization for a given API route. When IAM auth is enabled, clients need to use Signature Version 4 to sign their requests with their AWS credentials.
auth.jwt?
Type Input
<
Object
>
Enable JWT or JSON Web Token authorization for a given API route. When JWT auth is enabled, clients need to include a valid JWT in their requests.
You can configure JWT auth.
You can also use Cognito as the identity provider.
Where userPool
and userPoolClient
are:
auth.jwt.audiences
Type Input
<
Input
<
string
>
[]
>
List of the intended recipients of the JWT. A valid JWT must provide an aud
that matches at least one entry in this list.
auth.jwt.identitySource?
Type Input
<
string
>
Default “$request.header.Authorization”
Specifies where to extract the JWT from the request.
auth.jwt.issuer
Type Input
<
string
>
Base domain of the identity provider that issues JSON Web Tokens.
auth.jwt.scopes?
Type Input
<
Input
<
string
>
[]
>
Defines the permissions or access levels that the JWT grants. If the JWT does not have the required scope, the request is rejected. By default it does not require any scopes.
transform?
Type Object
Transform how this component creates its underlying resources.
transform.authorizer?
Type AuthorizerArgs
|
(
args
:
AuthorizerArgs
=>
void
)
Transform the API Gateway authorizer resource.
transform.integration?
Type IntegrationArgs
|
(
args
:
IntegrationArgs
=>
void
)
Transform the API Gateway HTTP API integration resource.