Skip to content

ApiGatewayV1

Reference doc for the `sst.aws.ApiGatewayV1` component.

The ApiGatewayV1 component lets you add an Amazon API Gateway REST API to your app.

Create the API

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

Add routes

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

Configure the routes

You can configure the route and its handler function.

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

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.

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

You can set it through the transform.

new sst.aws.ApiGatewayV1("MyApi", {
transform: {
route: {
handler: {
memory: "2048 MB"
}
}
}
});
api.route("GET /", "src/get.handler");
api.route("POST /", "src/post.handler");

Constructor

new ApiGatewayV1(name, args?, opts?)

Parameters

ApiGatewayV1Args

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.

endpoint?

Type Input<Object>

Default {type: “edge”}

Configure the API Gateway endpoint.

{
endpoint: {
type: "regional"
}
}

endpoint.type

Type edge | regional | private

The type of the API Gateway REST API endpoint.

endpoint.vpcEndpointIds?

Type Input<Input<string>[]>

The VPC endpoint IDs for the private endpoint.

transform?

Type Object

Transform how this component creates its underlying resources.

transform.accessLog?

Type LogGroupArgs | (args: LogGroupArgs => void)

Transform the CloudWatch LogGroup resource used for access logs.

transform.api?

Type RestApiArgs | (args: RestApiArgs => void)

Transform the API Gateway REST API resource.

transform.deployment?

Type DeploymentArgs | (args: DeploymentArgs => void)

Transform the API Gateway REST API deployment 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.

{
transform: {
route: {
handler: {
memory: "2048 MB"
},
}
}
}

Enable IAM auth for all our routes.

{
transform: {
route: {
args: (props) => {
props.auth = { iam: true };
}
}
}
}
transform.route.args?

Type ApiGatewayV1RouteArgs | (args: ApiGatewayV1RouteArgs => void)

Transform the arguments for the route.

transform.route.handler?

Type FunctionArgs | (args: FunctionArgs => void)

Transform the handler function of the route.

transform.stage?

Type StageArgs | (args: StageArgs => void)

Transform the API Gateway REST API stage resource.

Properties

nodes

Type Object

The underlying resources this component creates.

nodes.api

Type RestApi

The Amazon API Gateway REST API

nodes.logGroup

Type undefined | LogGroup

The CloudWatch LogGroup for the access logs.

url

Type Output<string>

The URL of the API.

SDK

The following are accessible through the SDK at runtime.

  • url string

    The URL of the API.

Methods

addAuthorizer

addAuthorizer(args)

Parameters

Returns ApiGatewayV1Authorizer

Add an authorizer to the API Gateway REST API.

Here’s how you add a Lambda TOKEN authorizer.

api.addAuthorizer({
name: "myAuthorizer",
tokenFunction: "src/authorizer.index",
});

Add a Lambda REQUEST authorizer.

api.addAuthorizer({
name: "myAuthorizer",
requestFunction: "src/authorizer.index",
});

Add a Cognito User Pool authorizer.

const userPool = new aws.cognito.UserPool();
api.addAuthorizer({
name: "myAuthorizer",
userPools: [userPool.arn],
});

Customize the authorizer.

api.addAuthorizer({
name: "myAuthorizer",
tokenFunction: "src/authorizer.index",
ttl: 30,
});

deploy

deploy()

Returns void

Create a deployment for the API Gateway REST API.

route

route(route, handler, args?)

Parameters

Returns ApiGatewayV1LambdaRoute

Add a route to the API Gateway REST API. The route is a combination of an HTTP method and a path, {METHOD} /{path}.

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.

When a request comes in, the API Gateway will look for the most specific match.

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"
});

ApiGatewayV1AuthorizerArgs

identitySource?

Type Input<string>

Default “method.request.header.Authorization”

Specifies where to extract the authorization token from the request.

{
identitySource: "method.request.header.AccessToken"
}

name

Type string

The name of the authorizer.

{
name: "myAuthorizer",
tokenFunction: "src/authorizer.index",
}

requestFunction?

Type Input<string | FunctionArgs>

The Lambda REQUEST authorizer function.

{
name: "myAuthorizer",
requestFunction: "src/authorizer.index",
}

tokenFunction?

Type Input<string | FunctionArgs>

The Lambda TOKEN authorizer function.

{
name: "myAuthorizer",
tokenFunction: "src/authorizer.index",
}

transform?

Type Object

Transform how this component creates its underlying resources.

transform.authorizer?

Type AuthorizerArgs | (args: AuthorizerArgs => void)

Transform the API Gateway authorizer resource.

ttl?

Type Input<number>

Default 300

Time to live for cached authorizer results in seconds.

{
ttl: 30
}

userPools?

Type Input<Input<string>[]>

A list of user pools used for the authorizer.

{
name: "myAuthorizer",
userPools: [userPool.arn],
}

Where userPool is:

const userPool = new aws.cognito.UserPool();

ApiGatewayV1RouteArgs

auth?

Type Input<Object>

Enable auth for your REST API.

{
auth: {
iam: true
}
}

auth.cognito?

Type Input<Object>

Enable Cognito User Pool authorization for a given API route.

You can configure JWT auth.

{
auth: {
cognito: {
authorizer: myAuthorizer.id,
scopes: ["read:profile", "write:profile"],
}
}
}

Where myAuthorizer is:

const userPool = new aws.cognito.UserPool();
const myAuthorizer = api.addAuthorizer({
name: "MyAuthorizer",
userPools: [userPool.arn],
});
auth.cognito.authorizer

Type Input<string>

Authorizer ID of the Cognito User Pool authorizer.

auth.cognito.scopes?

Type Input<Input<string>[]>

Defines the permissions or access levels that the authorization token grants.

auth.custom?

Type Input<string>

Enable custom Lambda authorization for a given API route. Pass in the authorizer ID.

{
auth: {
custom: myAuthorizer.id
}
}

Where myAuthorizer is:

const userPool = new aws.cognito.UserPool();
const myAuthorizer = api.addAuthorizer({
name: "MyAuthorizer",
userPools: [userPool.arn],
});

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.

transform?

Type Object

Transform how this component creates its underlying resources.

transform.integration?

Type IntegrationArgs | (args: IntegrationArgs => void)

Transform the API Gateway HTTP API integration resource.

transform.route?

Type RouteArgs | (args: RouteArgs => void)

Transform the API Gateway HTTP API route resource.