ApiGatewayWebSocket
Reference doc for the `sst.aws.ApiGatewayWebSocket` component.
The ApiGatewayWebSocket
component lets you add an Amazon API Gateway WebSocket API
to your app.
Create the API
Add a custom domain
Add routes
Constructor
Parameters
-
name
string
-
args?
ApiGatewayWebSocketArgs
-
opts?
ComponentResourceOptions
ApiGatewayWebSocketArgs
accessLog?
Type Input
<
Object
>
Default {retention: “1 month”}
Configure the API Gateway logs in CloudWatch. By default, access logs are enabled and kept for 1 month.
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 1 month
The duration the API Gateway logs are kept in CloudWatch.
domain?
Type Input
<
string
|
Object
>
Set a custom domain for your WebSocket 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.nameId?
Type Input
<
string
>
Use an existing API Gateway domain name.
By default, a new API Gateway domain name is created. If you’d like to use an existing
domain name, set the nameId
to the ID of the domain name and do not pass in name
.
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/
.
By 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
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the CloudWatch LogGroup resource used for access logs.
transform.api?
Type ApiArgs
|
(
args
:
ApiArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the API Gateway WebSocket API resource.
transform.domainName?
Type DomainNameArgs
|
(
args
:
DomainNameArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the API Gateway WebSocket API domain name resource.
transform.route?
Type Object
Transform the routes. This can be used to customize the handler function and the arguments for each route.
transform.route.args?
Type ApiGatewayWebSocketRouteArgs
|
(
args
:
ApiGatewayWebSocketRouteArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the arguments for the route.
transform.route.handler?
Type FunctionArgs
|
(
args
:
FunctionArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the handler function for the route.
transform.stage?
Type StageArgs
|
(
args
:
StageArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the API Gateway WebSocket API stage resource.
Properties
managementEndpoint
Type Output
<
string
>
The management endpoint for the API used by the API Gateway Management API client. This is useful for sending messages to connected clients.
nodes
Type Object
The underlying resources this component creates.
nodes.api
Type Api
The Amazon API Gateway V2 API.
nodes.logGroup
Type LogGroup
The CloudWatch LogGroup for the access logs.
nodes.domainName
Type Output
<
DomainName
>
The API Gateway HTTP API domain name.
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
Use the SDK in your runtime to interact with your infrastructure.
Links
This is accessible through the Resource
object in the SDK.
-
managementEndpoint
string
The management endpoint for the API used by the API Gateway Management API client. This is useful for sending messages to connected clients.
-
url
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
Input
<
string
|
FunctionArgs
|
“arn:aws:lambda:${string}”
>
- Configure the route.
Returns ApiGatewayWebSocketRoute
Add a route to the API Gateway WebSocket API.
There are three predefined routes:
$connect
: When the client connects to the API.$disconnect
: When the client or the server disconnects from the API.$default
: The default or catch-all route.
In addition, you can create custom routes. When a request comes in, the API Gateway
will look for the specific route defined by the user. If no route matches, the $default
route will be invoked.
Add a simple route.
Add a predefined route.
Enable auth for a route.
Customize the route handler.
Or pass in the ARN of an existing Lambda function.
ApiGatewayWebSocketRouteArgs
auth?
Type Input
<
Object
>
Enable auth for your WebSocket API.
auth.iam?
Type Input
<
boolean
>
Default false
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.
transform?
Type Object
Transform how this component creates its underlying resources.
transform.integration?
Type IntegrationArgs
|
(
args
:
IntegrationArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the API Gateway WebSocket API integration resource.
transform.route?
Type RouteArgs
|
(
args
:
RouteArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the API Gateway WebSocket API route resource.