Skip to content

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

const api = new sst.aws.ApiGatewayV2("MyApi");

Add a custom domain

new sst.aws.ApiGatewayV2("MyApi", {
domain: "api.domain.com"
});

Add routes

api.route("GET /", "src/get.handler");
api.route("POST /", "src/post.handler");

Constructor

new ApiGatewayV2(name, args?, opts?)

Parameters

Methods

route

route(route, handler, args?)

Parameters

Returns ApiGatewayV2Route

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.

api.route("GET /", "src/get.handler");

Match any HTTP method.

api.route("ANY /", "src/route.handler");

Add a default route.

api.route("GET /", "src/get.handler")
api.route($default, "src/default.handler");

Add a parameterized route.

api.route("GET /notes/{id}", "src/get.handler");

Add a greedy route.

api.route("GET /notes/{proxy+}", "src/greedy.handler");

Enable auth for a route.

api.route("GET /", "src/get.handler")
api.route("POST /", "src/post.handler", {
auth: {
iam: true
}
});

Customize the route handler.

api.route("GET /", {
handler: "src/get.handler",
memory: "2048 MB"
});

Properties

nodes

Type Object

The underlying resources this component creates.

nodes.api

Type Api

The Amazon API Gateway HTTP API

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.

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.

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: "1 week"
}
}

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. Supports domains hosted either on Route 53 or outside AWS.

{
domain: "api.domain.com"
}

domain.cert?

Type Input<string>

The ARN of an existing certificate in the us-east-1 region in AWS Certificate Manager to use for the domain. By default, SST will create a certificate with the domain name. The certificate will be created in the us-east-1(N. Virginia) region as required by AWS CloudFront.

{
domain: {
name: "domain.com",
cert: "arn:aws:acm:us-east-1:112233445566:certificate/3a958790-8878-4cdc-a396-06d95064cf63"
}
}

domain.dns?

Type Input<false | sst.aws.dns | sst.cloudflare.dns | sst.vercel.dns>

Default sst.aws.dns

The DNS adapter you want to use for managing DNS records.

Specify the hosted zone ID for the domain.

{
domain: {
name: "domain.com",
dns: sst.aws.dns({
zone: "Z2FDTNDATAQYW2"
})
}
}

Domain is hosted on Cloudflare.

{
domain: {
name: "domain.com",
dns: sst.cloudflare.dns()
}
}

domain.name

Type Input<string>

The custom domain you want to use. Supports domains hosted on Route 53 or outside AWS.

{
domain: "domain.com"
}

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.

{
domain: {
name: "api.domain.com",
path: "v1"
}
}

The full URL of the API will be https://api.domain.com/v1/.

Be default there is no base path, so if the name is api.domain.com, the full URL will be https://api.domain.com.

transform?

Type Object

Transform how this component creates its underlying resources.

transform.accessLog?

Type LogGroupArgs | (args: LogGroupArgs => LogGroupArgs | void)

Transform the CloudWatch LogGroup resource used for access logs.

transform.api?

Type ApiArgs | (args: ApiArgs => ApiArgs | void)

Transform the API Gateway HTTP API resource.

transform.domainName?

Type DomainNameArgs | (args: DomainNameArgs => DomainNameArgs | void)

Transform the API Gateway HTTP API domain name resource.

transform.stage?

Type StageArgs | (args: StageArgs => StageArgs | void)

Transform the API Gateway HTTP API stage resource.

ApiGatewayV2Route

function

Type Output<Function>

The Lambda function.

integration

Type Integration

The API Gateway HTTP API integration.

permission

Type Permission

The Lambda permission.

route

Type Output<Route>

The API Gateway HTTP API route.

ApiGatewayV2RouteArgs

auth?

Type Input<Object>

Enable auth for your HTTP API.

{
auth: {
iam: true
}
}

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.

{
auth: {
jwt: {
issuer: "https://issuer.com/",
audiences: ["https://api.example.com"],
scopes: ["read:profile", "write:profile"],
identitySource: "$request.header.AccessToken"
}
}
}

You can also use Cognito as the identity provider.

{
auth: {
jwt: {
audiences: [userPoolClient.id],
issuer: $interpolate`https://cognito-idp.${aws.getArnOutput(userPool).region}.amazonaws.com/${userPool.id}`,
}
}
}

Where userPool and userPoolClient are:

const userPool = new aws.cognito.UserPool();
const userPoolClient = new aws.cognito.UserPoolClient();
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 => AuthorizerArgs | void)

Transform the API Gateway authorizer resource.

transform.integration?

Type IntegrationArgs | (args: IntegrationArgs => IntegrationArgs | void)

Transform the API Gateway HTTP API integration resource.

transform.route?

Type RouteArgs | (args: RouteArgs => RouteArgs | void)

Transform the API Gateway HTTP API route resource.