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.

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

Configure the route handler

You can configure the route handler function.

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

Default props for all routes

You can use the transform to set some default props 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.

const api = new sst.aws.ApiGatewayV1("MyApi", {
  transform: {
    route: {
      handler: (args, opts) => {
        // Set the default if it's not set by the route
        args.memory ??= "2048 MB";
      }
    }
  }
});

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

With this we set the memory if it’s not overridden by the route.

Constructor

new ApiGatewayV1(name, args?, opts?)

Parameters

name string
args? ApiGatewayV1Args
opts? ComponentResourceOptions

ApiGatewayV1Args

accessLog?

Type Input<Object>

retention?

Default {retention: “1 month”}

Configure the API Gateway logs in CloudWatch. By default, access logs are enabled and kept for 1 month.

{
  accessLog: {
    retention: "forever"
  }
}

accessLog.retention?

Default 1 month

The duration the API Gateway logs are kept in CloudWatch.

cors?

Type Input<boolean>

Default true

Enable the CORS (Cross-origin resource sharing) settings for your REST API.

Disable CORS.

{
  cors: false
}

domain?

Type Input<string | Object>

cert?
dns?
name
path?

Set a custom domain for your REST 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.

{
  domain: "example.com"
}

For domains hosted on Cloudflare.

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

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 set dns to false.
Add the DNS records in your provider to point to the API Gateway URL.

{
  domain: {
    name: "example.com",
    dns: false,
    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 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.

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

Use a domain hosted on Cloudflare, needs the Cloudflare provider.

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

Use a domain hosted on Vercel, needs the Vercel provider.

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

domain.name

Type Input<string>

The custom domain you want to use.

{
  domain: {
    name: "example.com"
  }
}

Can also include subdomains based on the current stage.

{
  domain: {
    name: `${$app.stage}.example.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.example.com",
    path: "v1"
  }
}

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.

endpoint?

Type Input<Object>

type
vpcEndpointIds?

Default {type: “edge”}

Configure the API Gateway REST API endpoint.

By default, it’s an edge endpoint, meaning that a CloudFront distribution is created for the API. This could help in cases where requests are geographically distributed.

On the other hand, regional endpoints are deployed in a specific AWS region and are intended to be accessed directly by clients within or near that region.

And a private endpoints allow access to the API only from within a specified Amazon VPC (Virtual Private Cloud) using VPC endpoints. These endpoints do not expose the API to the public internet.

To create a regional endpoint.

{
  endpoint: {
    type: "regional"
  }
}

And to create a private endpoint.

{
  endpoint: {
    type: "private",
    vpcEndpointIds: ["vpce-0dccab6fb1e828f36"]
  }
}

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

accessLog?
api?
deployment?
domainName?
route? Object
- args?
- handler?
stage?

Transform how this component creates its underlying resources.

transform.accessLog?

Type LogGroupArgs | (args: LogGroupArgs, opts: ComponentResourceOptions, name: string) => void

Transform the CloudWatch LogGroup resource used for access logs.

transform.api?

Type RestApiArgs | (args: RestApiArgs, opts: ComponentResourceOptions, name: string) => void

Transform the API Gateway REST API resource.

transform.deployment?

Type DeploymentArgs | (args: DeploymentArgs, opts: ComponentResourceOptions, name: string) => void

Transform the API Gateway REST API deployment resource.

transform.domainName?

Type DomainNameArgs | (args: DomainNameArgs, opts: ComponentResourceOptions, name: string) => void

Transform the API Gateway REST 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 default 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 setting a default memory of 2048 MB for our routes.

{
  transform: {
    route: {
      handler: (args, opts) => {
        // Set the default if it's not set by the route
        args.memory ??= "2048 MB";
      }
    }
  }
}

Defaulting to IAM auth for all our routes.

{
  transform: {
    route: {
      args: (props) => {
        // Set the default if it's not set by the route
        props.auth ??= { iam: true };
      }
    }
  }
}

transform.route.args?

Type ApiGatewayV1RouteArgs | (args: ApiGatewayV1RouteArgs, 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 of the route.

transform.stage?

Type StageArgs | (args: StageArgs, opts: ComponentResourceOptions, name: string) => void

Transform the API Gateway REST API stage resource.

Properties

nodes

Type Object

api
logGroup
stage

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.

nodes.stage

Type undefined | Stage

The Amazon API Gateway REST API stage

url

Type Output<string>

The URL of the API.

SDK

Use the SDK in your runtime to interact with your infrastructure.

Methods

addAuthorizer

addAuthorizer(args)

Parameters

args ApiGatewayV1AuthorizerArgs
Configure the authorizer.

Returns ApiGatewayV1Authorizer

Add an authorizer to the API Gateway REST API.

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.

Due to the way API Gateway V1 is created internally, you’ll need to call this method after you’ve added all your routes.

route

route(route, handler, args?)

Parameters

route string
The path for the route.
handler Input<string | FunctionArgs | “arn:aws:lambda:${string}”>
The function that’ll be invoked.
args? ApiGatewayV1RouteArgs
Configure the route.

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.

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

Or pass in the ARN of an existing Lambda function.

api.route("GET /", "arn:aws:lambda:us-east-1:123456789012:function:my-function");

routeIntegration

routeIntegration(route, integration, args?)

Parameters

route string
The path for the route.
integration ApiGatewayV1IntegrationArgs
The integration configuration.
args? ApiGatewayV1RouteArgs
Configure the route.

Returns ApiGatewayV1IntegrationRoute

Add a custom integration to the API Gateway REST API.

Learn more about integrations for REST APIs.

Add a route to trigger a Step Functions state machine execution.

api.routeIntegration("POST /run-my-state-machine", {
  type: "aws",
  uri: "arn:aws:apigateway:us-east-1:states:startExecution",
  credentials: "arn:aws:iam::123456789012:role/apigateway-execution-role",
  integrationHttpMethod: "POST",
  requestTemplates: {
    "application/json": JSON.stringify({
      input: "$input.json('$')",
      stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:MyStateMachine",
    }),
  },
  passthroughBehavior: "when-no-match",
});

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

requestFunction?

Type Input<string | FunctionArgs>

The Lambda request authorizer function. Takes the handler path or the function args.

{
  requestFunction: "src/authorizer.index"
}

tokenFunction?

Type Input<string | FunctionArgs>

The Lambda token authorizer function. Takes the handler path or the function args.

{
  tokenFunction: "src/authorizer.index"
}

transform?

Type Object

authorizer?

Transform how this component creates its underlying resources.

transform.authorizer?

Type AuthorizerArgs | (args: AuthorizerArgs, opts: ComponentResourceOptions, name: string) => 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 as the authorizer.

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

Where userPool is:

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

ApiGatewayV1DomainArgs

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 set dns to false.
Add the DNS records in your provider to point to the API Gateway URL.

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

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.

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

Use a domain hosted on Cloudflare, needs the Cloudflare provider.

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

Use a domain hosted on Vercel, needs the Vercel provider.

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

name

Type Input<string>

The custom domain you want to use.

{
  domain: {
    name: "example.com"
  }
}

Can also include subdomains based on the current stage.

{
  domain: {
    name: `${$app.stage}.example.com`
  }
}

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.example.com",
    path: "v1"
  }
}

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.

ApiGatewayV1IntegrationArgs

credentials?

Type Input<string>

The credentials to use to call the AWS service.

integrationHttpMethod?

The HTTP method to use to call the integration.

passthroughBehavior?

Type Input<“when-no-match” | “never” | “when-no-templates”>

The passthrough behavior to use to call the integration.

Required if requestTemplates is set.

requestParameters?

Type Input<Record<string, Input<string>>>

Map of request query string parameters and headers that should be passed to the backend responder.

requestTemplates?

Type Input<Record<string, Input<string>>>

Map of the integration’s request templates.

type

Type Input<“aws” | “aws-proxy” | “mock” | “http” | “http-proxy”>

The type of the API Gateway REST API integration.

uri?

Type Input<string>

The URI of the API Gateway REST API integration.

ApiGatewayV1RouteArgs

auth?

Type Input<false | Object>

cognito? Input<Object>
- authorizer
- scopes?
custom?
iam?

Default false

Enable auth for your REST API. By default, auth is disabled.

{
  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<boolean>

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

integration?
method?

Transform how this component creates its underlying resources.

transform.integration?

Type IntegrationArgs | (args: IntegrationArgs, opts: ComponentResourceOptions, name: string) => void

Transform the API Gateway REST API integration resource.

transform.method?

Type MethodArgs | (args: MethodArgs, opts: ComponentResourceOptions, name: string) => void

Transform the API Gateway REST API method resource.

ApiGatewayV1

Create the API

Add routes

Configure the routes

Configure the route handler

Default props for all routes

Constructor

Parameters

ApiGatewayV1Args

accessLog?

accessLog.retention?

cors?

domain?

domain.cert?

domain.dns?

domain.name

domain.path?

endpoint?

endpoint.type

endpoint.vpcEndpointIds?

transform?

transform.accessLog?

transform.api?

transform.deployment?

transform.domainName?

transform.route?

transform.route.args?

transform.route.handler?

transform.stage?

Properties

nodes

nodes.api

nodes.logGroup

nodes.stage

url

SDK

Links

Methods

addAuthorizer

Parameters

deploy

route

Parameters

routeIntegration

Parameters

ApiGatewayV1AuthorizerArgs

identitySource?

name

requestFunction?

tokenFunction?

transform?

transform.authorizer?

ttl?

userPools?

ApiGatewayV1DomainArgs

cert?

dns?

name

path?

ApiGatewayV1IntegrationArgs

credentials?

integrationHttpMethod?

passthroughBehavior?

requestParameters?

requestTemplates?

type

uri?

ApiGatewayV1RouteArgs

auth?

auth.cognito?

auth.cognito.authorizer

auth.cognito.scopes?

auth.custom?

auth.iam?

transform?

transform.integration?

transform.method?