Skip to main content

Api

caution

This is the SST v1.x Constructs doc. SST v2 is now released. If you are using v2, see the v2 Constructs doc. If you are looking to upgrade to v2, check out the upgrade steps.

The Api construct is a higher level CDK construct that makes it easy to create an API. It provides a simple way to define the routes in your API. And allows you to configure the specific Lambda functions if necessary. It also allows you to configure authorization and custom domains.

Examples

The Api construct is designed to make it easy to get started with, while allowing for a way to fully configure it as well. Let's look at how, through a couple of examples.

Using the minimal config

import { Api } from "@serverless-stack/resources";

new Api(stack, "Api", {
routes: {
"GET /notes": "src/list.main",
"POST /notes": "src/create.main",
"GET /notes/{id}": "src/get.main",
"PUT /notes/{id}": "src/update.main",
"DELETE /notes/{id}": "src/delete.main",
},
});

Configuring routes

Using ANY methods

You can use the ANY method to match all methods that you haven't defined.

new Api(stack, "Api", {
routes: {
"GET /notes": "src/list.main",
"ANY /notes": "src/any.main",
},
});

Using path variable

new Api(stack, "Api", {
routes: {
"GET /notes" : "src/list.main",
"GET /notes/{id}": "src/get.main",
},
});

Using greedy path variable

A path variable {proxy+} catches all child routes. The greedy path variable must be at the end of the resource path.

new Api(stack, "Api", {
routes: {
"GET /notes" : "src/list.main",
"GET /notes/{proxy+}": "src/greedy.main",
},
});

Using catch-all route

To add a catch-all route, add a route called $default. This will catch requests that don't match any other routes.

new Api(stack, "Api", {
routes: {
"GET /notes": "src/list.main",
"POST /notes": "src/create.main",
"$default" : "src/default.main",
},
});

Lazily adding routes

Add routes after the API has been created.

const api = new Api(stack, "Api", {
routes: {
"GET /notes": "src/list.main",
"POST /notes": "src/create.main",
},
});

api.addRoutes(stack, {
"GET /notes/{id}": "src/get.main",
"PUT /notes/{id}": "src/update.main",
"DELETE /notes/{id}": "src/delete.main",
});

Configuring Function routes

Specifying function props for all the routes

You can set some function props and have them apply to all the routes.

new Api(stack, "Api", {
defaults: {
function: {
timeout: 20,
environment: { tableName: table.tableName },
permissions: [table],
},
},
routes: {
"GET /notes": "src/list.main",
"POST /notes": "src/create.main",
},
});

Configuring an individual route

Configure each Lambda function separately.

new Api(stack, "Api", {
routes: {
"GET /notes": {
function: {
handler: "src/list.main",
timeout: 20,
environment: { tableName: table.tableName },
permissions: [table],
},
},
},
});

Note that, you can set the defaults.function while using the function per route. The function will just override the defaults.function. Except for the environment, the layers, and the permissions properties, that will be merged.

new Api(stack, "Api", {
defaults: {
function: {
timeout: 20,
environment: { tableName: table.tableName },
permissions: [table],
},
},
routes: {
"GET /notes": {
function: {
handler: "list.main",
timeout: 10,
environment: { bucketName: bucket.bucketName },
permissions: [bucket],
},
},
"POST /notes": "create.main",
},
});

So in the above example, the GET /notes function doesn't use the timeout that is set in the defaults.function. It'll instead use the one that is defined in the function definition (10 seconds). And the function will have both the tableName and the bucketName environment variables set; as well as permissions to both the table and the bucket.

Attaching permissions for the entire API

Allow the entire API to access S3.

const api = new Api(stack, "Api", {
routes: {
"GET /notes" : "src/list.main",
"POST /notes" : "src/create.main",
"GET /notes/{id}": "src/get.main",
"PUT /notes/{id}": "src/update.main",
"DELETE /notes/{id}": "src/delete.main",
},
});

api.attachPermissions(["s3"]);

Attaching permissions for a specific route

Allow one of the routes to access S3.

const api = new Api(stack, "Api", {
routes: {
"GET /notes" : "src/list.main",
"POST /notes" : "src/create.main",
"GET /notes/{id}": "src/get.main",
"PUT /notes/{id}": "src/update.main",
"DELETE /notes/{id}": "src/delete.main",
},
});

api.attachPermissionsToRoute("GET /notes", ["s3"]);

Getting the function for a route

const api = new Api(stack, "Api", {
routes: {
"GET /notes": "src/list.main",
"POST /notes": "src/create.main",
"GET /notes/{id}": "src/get.main",
"PUT /notes/{id}": "src/update.main",
"DELETE /notes/{id}": "src/delete.main",
},
});

const listFunction = api.getFunction("GET /notes");

Configuring ALB routes

You can configure a route to integrate with Application Load Balancers in your VPC.

new Api(stack, "Api", {
routes: {
"GET /": {
type: "alb",
cdk: {
albListener,
}
},
},
});

Configuring HTTP proxy routes

You can configure a route to pass the entire request to a publicly routable HTTP endpoint.

new Api(stack, "Api", {
routes: {
"GET /": {
type: "url",
url: "http://domain.com",
},
},
});

Custom domains

You can configure the API with a custom domain hosted either on Route 53 or externally.

Using the basic config

new Api(stack, "Api", {
customDomain: "api.domain.com",
routes: {
"GET /notes": "src/list.main",
},
});

Configuring with a wildcard

new Api(stack, "Api", {
customDomain: "*.domain.com",
routes: {
"GET /notes": "src/list.main",
},
});

Using the full config

new Api(stack, "Api", {
customDomain: {
domainName: "api.domain.com",
hostedZone: "domain.com",
path: "v1",
},
routes: {
"GET /notes": "src/list.main",
},
});

Mapping multiple APIs to the same domain

const usersApi = new Api(stack, "UsersApi", {
customDomain: {
domainName: "api.domain.com",
path: "users",
},
});

new Api(stack, "PostsApi", {
customDomain: {
path: "posts",
cdk: {
domainName: usersApi.cdk.domainName,
}
},
});

Importing an existing API Gateway custom domain

import { DomainName } from "@aws-cdk/aws-apigatewayv2-alpha";

new Api(stack, "Api", {
customDomain: {
path: "newPath",
cdk: {
domainName: DomainName.fromDomainNameAttributes(stack, "MyDomain", {
name,
regionalDomainName,
regionalHostedZoneId,
}),
},
},
routes: {
"GET /notes": "src/list.main",
},
});

Importing an existing certificate

import { Certificate } from "aws-cdk-lib/aws-certificatemanager";

new Api(stack, "Api", {
customDomain: {
domainName: "api.domain.com",
cdk: {
certificate: Certificate.fromCertificateArn(stack, "MyCert", certArn),
},
},
routes: {
"GET /notes": "src/list.main",
},
});

Specifying a hosted zone

If you have multiple hosted zones for a given domain, you can choose the one you want to use to configure the domain.

import { HostedZone } from "aws-cdk-lib/aws-route53";

new Api(stack, "Api", {
customDomain: {
domainName: "api.domain.com",
cdk: {
hostedZone: HostedZone.fromHostedZoneAttributes(stack, "MyZone", {
hostedZoneId,
zoneName,
}),
},
},
routes: {
"GET /notes": "src/list.main",
},
});

Loading domain name from SSM parameter

If you have the domain name stored in AWS SSM Parameter Store, you can reference the value as the domain name:

import { StringParameter } from "aws-cdk-lib/aws-ssm";

const rootDomain = StringParameter.valueForStringParameter(stack, `/myApp/domain`);

new Api(stack, "Api", {
customDomain: {
domainName: `api.${rootDomain}`,
cdk: {
hostedZone: HostedZone.fromHostedZoneAttributes(stack, "MyZone", {
hostedZoneId,
zoneName,
}),
},
},
routes: {
"GET /notes": "src/list.main",
},
});

Note that, normally SST will look for a hosted zone by stripping out the first part of the domainName. But this is not possible when the domainName is a reference. So you'll need to specify the cdk.hostedZone explicitly.

Using externally hosted domain

import { Certificate } from "aws-cdk-lib/aws-certificatemanager";

new Api(stack, "Api", {
customDomain: {
isExternalDomain: true,
domainName: "api.domain.com",
cdk: {
certificate: Certificate.fromCertificateArn(stack, "MyCert", certArn),
},
},
routes: {
"GET /notes": "src/list.main",
},
});

Note that you can also migrate externally hosted domains to Route 53 by following this guide.

Authorization

You can use IAM, JWT, or a Lambda authorizer to add auth to your APIs.

Adding IAM authorization

You can secure all your API routess by setting the defaults.authorizer.

new Api(stack, "Api", {
defaults: {
authorizer: "iam",
},
routes: {
"GET /notes": "list.main",
"POST /notes": "create.main",
},
});

Adding IAM authorization to a specific route

You can also secure specific routes in your API.

new Api(stack, "Api", {
routes: {
"GET /public": "src/public.main",
"GET /private": {
authorizer: "iam",
function: "src/private.main",
},
},
});

Adding JWT authorization

JWT allows authorized users to access your API. Note that, this is a different authorization method when compared to using iam, which allows you to secure other AWS resources as well.

new Api(stack, "Api", {
authorizers: {
myAuthorizer: {
type: "jwt",
jwt: {
issuer: "https://myorg.us.auth0.com",
audience: ["UsGRQJJz5sDfPQDs6bhQ9Oc3hNISuVif"],
}
},
},
defaults: {
authorizer: "myAuthorizer",
},
routes: {
"GET /notes": "list.main",
"POST /notes": "create.main",
},
});

Adding JWT authorization to a specific route

You can also secure specific routes using JWT by setting the authorizer per route.

new Api(stack, "Api", {
authorizers: {
myAuthorizer: {
type: "jwt",
jwt: {
issuer: "https://myorg.us.auth0.com",
audience: ["UsGRQJJz5sDfPQDs6bhQ9Oc3hNISuVif"],
}
},
},
routes: {
"GET /public": "src/public.main",
"GET /private": {
authorizer: "myAuthorizer",
function: "src/private.main",
},
},
});

Using Cognito User Pool as the JWT authorizer

JWT can also use a Cognito User Pool as an authorizer.

new Api(stack, "Api", {
authorizers: {
myAuthorizer: {
type: "user_pool",
userPool: {
id: userPool.userPoolId,
clientIds: [userPoolClient.userPoolClientId],
}
},
},
defaults: {
authorizer: "myAuthorizer",
authorizationScopes: ["user.id", "user.email"],
},
routes: {
"GET /notes": "list.main",
"POST /notes": "create.main",
},
});

Adding Lambda authorization

You can also use a Lambda function to authorize users to access your API. Like using JWT and IAM, the Lambda authorizer is another way to secure your API.

import { Function, Api } from "@serverless-stack/resources";

new Api(stack, "Api", {
authorizers: {
myAuthorizer: {
type: "lambda",
function: new Function(stack, "Authorizer", {
handler: "src/authorizer.main",
}),
resultsCacheTtl: "30 seconds",
},
},
defaults: {
authorizer: "myAuthorizer",
},
routes: {
"GET /notes": "list.main",
"POST /notes": "create.main",
},
});

Note that resultsCacheTtl configures how long the authorization result will be cached.

Adding Lambda authorization to a specific route

You can also secure specific routes using a Lambda authorizer by setting the authorizer per route.

import { Function, Api } from "@serverless-stack/resources";

new Api(stack, "Api", {
authorizers: {
myAuthorizer: {
type: "lambda",
function: new Function(stack, "Authorizer", {
handler: "src/authorizer.main",
}),
resultsCacheTtl: "30 seconds",
},
},
routes: {
"GET /public": "src/public.main",
"GET /private": {
authorizer: "myAuthorizer",
function: "src/private.main",
},
},
});

Sharing an API authorizer

If defaults.authorizer is configured for the Api, it will be applied to all routes, across all stacks.

stacks/MainStack.js
const api = new Api(stack, "Api", {
authorizers: {
myAuthorizer: {
type: "lambda",
function: new Function(stack, "Authorizer", {
handler: "src/authorizer.main",
}),
resultsCacheTtl: "30 seconds",
},
},
defaults: {
authorizer: "myAuthorizer",
},
routes: {
"GET /notes": "src/list.main",
"POST /notes": "src/create.main",
},
});

this.api = api;
stacks/AnotherStack.js
api.addRoutes(stack, {
"GET /notes/{id}": "src/get.main",
"PUT /notes/{id}": "src/update.main",
"DELETE /notes/{id}": "src/delete.main",
});

In this case, the 3 routes added in the second stack are also secured by the Lambda authorizer.

Access log

Configuring the log format

Use a CSV format instead of default JSON format.

new Api(stack, "Api", {
accessLog:
"$context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId",
routes: {
"GET /notes": "src/list.main",
},
});

Configuring the log retention setting

new Api(stack, "Api", {
accessLog: {
retention: "one_week",
},
routes: {
"GET /notes": "src/list.main",
},
});

CORS

Override the default behavior of allowing all methods, and only allow the GET method.

new Api(stack, "Api", {
cors: {
allowMethods: ["GET"],
},
routes: {
"GET /notes": "src/list.main",
},
});

GraphQL

Add a GraphQL route using a Code-first GraphQL setup, configured using Pothos.

new Api(stack, "Api", {
routes: {
"POST /graphql": {
type: "graphql",
function: "src/graphql.main",
pothos: {
schema: "backend/functions/graphql/schema.ts",
output: "graphql/schema.graphql",
commands: [
"./genql graphql/graphql.schema graphql/
]
}
},
},
});

Advanced examples

Throttling

new Api(stack, "Api", {
defaults: {
throttle: {
rate: 2000,
burst: 100,
}
},
routes: {
"GET /notes": "list.main",
"POST /notes": "create.main",
},
});

Configuring the Http Api

Configure the internally created CDK HttpApi instance.

new Api(stack, "Api", {
cdk: {
httpApi: {
disableExecuteApiEndpoint: true,
},
},
routes: {
"GET /notes": "src/list.main",
},
});

Sharing an API across stacks

You can create the Api construct in one stack, and add routes in other stacks. To do this, return the API from your stack function.

stacks/MainStack.ts
import { Api, StackContext } from "@serverless-stack/resources";

export function MainStack({ stack }: StackContext) {
const api = new Api(stack, "Api", {
routes: {
"GET /notes": "src/list.main",
"POST /notes": "src/create.main",
},
});

return {
api
}
}

Then in another stack, utilize use to import the first stack's API. Finally, call addRoutes. Note that the AWS resources for the added routes will be created in AnotherStack.

stacks/AnotherStack.ts
import { StackContext, use } from "@serverless-stack/resources";
import { MainStack } from "./MainStack"

export function AnotherStack({ stack }: StackContext) {
const { api } = use(MainStack)
api.addRoutes(stack, {
"GET /notes/{id}": "src/get.main",
"PUT /notes/{id}": "src/update.main",
"DELETE /notes/{id}": "src/delete.main",
});
}

Using 1 role for all routes

By default, Api creates 1 IAM role for each Function handling a route. To have all Functions reuse the same role, manually create a role, and pass it into defaults.function.

Use attachPermissionsToRole to grant IAM permissions for the role.

import * as iam from "aws-cdk-lib/aws-iam";
import { attachPermissionsToRole } from "@serverless-stack/resources";

// Create an IAM role
const role = new iam.Role(stack, "ApiRole", {
assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"),
managedPolicies: [
{
managedPolicyArn: "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
}
]
});

// Attach permissions to role
attachPermissionsToRole(role, [
// ie. table
]);

// Use the role for all routes
new Api(stack, "Api", {
defaults: {
function: {
role,
},
},
routes: {
"GET /notes": "src/list.main",
"POST /notes": "src/create.main",
"GET /notes/{id}": "src/get.main",
"PUT /notes/{id}": "src/update.main",
"DELETE /notes/{id}": "src/delete.main",
},
});

Using Lambda container images

import * as lambda from "aws-cdk-lib/aws-lambda";

const fn = new lambda.DockerImageFunction(stack, "DockerFunction", {
code: lambda.DockerImageCode.fromImageAsset("path/to/Dockerfile/folder"),
});

new Api(stack, "Api", {
routes: {
"GET /": {
cdk: {
function: fn,
}
},
},
});

Using Lambda aliases

const fn = new Function(stack, "MyFunction", {
handler: "handler.main",
});
const alias = new lambda.Alias(stack, "MyAlias", {
aliasName: "hello",
version: fn.currentVersion,
});

new Api(stack, "Api", {
routes: {
"GET /": {
cdk: {
function: alias,
}
},
},
});

Importing an existing Http Api

Override the internally created CDK HttpApi instance.

import { HttpApi } from "@aws-cdk/aws-apigatewayv2-alpha";

new Api(stack, "Api", {
cdk: {
httpApi: HttpApi.fromHttpApiAttributes(stack, "MyHttpApi", {
httpApiId,
}),
},
routes: {
"GET /notes": "src/list.main",
},
});

Constructor

new Api(scope, id, props)

Parameters

ApiProps

accessLog?

Type : string | boolean | ApiAccessLogProps

Default : true

Enable CloudWatch access logs for this API

new Api(stack, "Api", {
accessLog: true
});
new Api(stack, "Api", {
accessLog: {
retention: "one_week",
},
});

authorizers?

Type : Record<string, ApiUserPoolAuthorizer | ApiJwtAuthorizer | ApiLambdaAuthorizer>

Define the authorizers for the API. Can be a user pool, JWT, or Lambda authorizers.

new Api(stack, "Api", {
authorizers: {
Authorizer: {
type: "user_pool",
userPool: {
id: userPool.userPoolId,
clientIds: [userPoolClient.userPoolClientId],
},
},
},
});

cors?

Type : boolean | ApiCorsProps

Default : true

CORS support applied to all endpoints in this API

new Api(stack, "Api", {
cors: {
allowMethods: ["GET"],
},
});

customDomain?

Type : string | ApiDomainProps

Specify a custom domain to use in addition to the automatically generated one. SST currently supports domains that are configured using Route 53

new Api(stack, "Api", {
customDomain: "api.example.com"
})
new Api(stack, "Api", {
customDomain: {
domainName: "api.example.com",
hostedZone: "domain.com",
path: "v1"
}
})

defaults.authorizationScopes?

Type : Array<string>

Default : []

An array of scopes to include in the authorization when using user_pool or jwt authorizers. These will be merged with the scopes from the attached authorizer.

defaults.authorizer?

Type : "none" | "iam" | string

The default authorizer for all the routes in the API.

new Api(stack, "Api", {
defaults: {
authorizer: "iam",
}
});
new Api(stack, "Api", {
authorizers: {
Authorizer: {
type: "user_pool",
userPool: {
id: userPool.userPoolId,
clientIds: [userPoolClient.userPoolClientId],
},
},
},
defaults: {
authorizer: "Authorizer",
}
});

defaults.function?

Type : FunctionProps

The default function props to be applied to all the Lambda functions in the API. The environment, permissions and layers properties will be merged with per route definitions if they are defined.

new Api(stack, "Api", {
defaults: {
function: {
timeout: 20,
environment: { tableName: table.tableName },
permissions: [table],
}
}
});

defaults.payloadFormatVersion?

Type : "1.0" | "2.0"

Default : "2.0"

The payload format version for all the endpoints in the API.

defaults.throttle.burst?

Type : number

The burst rate of the number of concurrent request for all the routes in the API.

new Api(stack, "Api", {
defaults: {
throttle: {
burst: 100
}
}
})

defaults.throttle.rate?

Type : number

The steady-state rate of the number of concurrent request for all the routes in the API.

new Api(stack, "Api", {
defaults: {
throttle: {
rate: 10
}
}
})

routes?

Type : Record<string, string | Function | ApiFunctionRouteProps | ApiHttpRouteProps | ApiAlbRouteProps | ApiGraphQLRouteProps | ApiPothosRouteProps>

Define the routes for the API. Can be a function, proxy to another API, or point to an ALB

new Api(stack, "api", {
routes: {
"GET /notes" : "src/list.main",
"GET /notes/{id}" : "src/get.main",
"$default": "src/default.main"
}
})

cdk.httpApi?

Type : IHttpApi | HttpApiProps

Import the underlying HTTP API or override the default configuration

import { HttpApi } from "@aws-cdk/aws-apigatewayv2-alpha";

new Api(stack, "Api", {
cdk: {
httpApi: HttpApi.fromHttpApiAttributes(stack, "MyHttpApi", {
httpApiId,
}),
}
});

cdk.httpStages?

Type : Array<Omit<HttpStageProps, "httpApi">>

Configures the stages to create for the HTTP API. Note that, a default stage is automatically created, unless the cdk.httpApi.createDefaultStage is set to `false.

import { HttpApi } from "@aws-cdk/aws-apigatewayv2-alpha";

new Api(stack, "Api", {
cdk: {
httpStages: [{
stageName: "dev",
autoDeploy: false,
}],
}
});

cdk.id?

Type : string

Allows you to override default id for this construct.

Properties

An instance of Api has the following properties.

customDomainUrl

Type : undefined | string

If custom domain is enabled, this is the custom domain URL of the Api.

note

If you are setting the base mapping for the custom domain, you need to include the trailing slash while using the custom domain URL. For example, if the domainName is set to api.domain.com and the path is v1, the custom domain URL of the API will be https://api.domain.com/v1/.

httpApiArn

Type : string

The ARN of the internally created API Gateway HTTP API

httpApiId

Type : string

The id of the internally created API Gateway HTTP API

id

Type : string

routes

Type : Array<string>

The routes for the Api

url

Type : string

The AWS generated URL of the Api.

cdk.accessLogGroup?

Type : LogGroup

If access logs are enabled, this is the internally created CDK LogGroup instance.

cdk.certificate?

Type : Certificate

If custom domain is enabled, this is the internally created CDK Certificate instance.

cdk.domainName?

Type : DomainName

If custom domain is enabled, this is the internally created CDK DomainName instance.

cdk.httpApi

Type : HttpApi

The internally created CDK HttpApi instance.

Methods

An instance of Api has the following methods.

addRoutes

addRoutes(scope, routes)

Parameters

Adds routes to the Api after it has been created.

api.addRoutes(stack, {
"GET /notes/{id}": "src/get.main",
"PUT /notes/{id}": "src/update.main",
"DELETE /notes/{id}": "src/delete.main",
});

attachPermissions

attachPermissions(permissions)

Parameters

Attaches the given list of permissions to all the routes. This allows the functions to access other AWS resources.

api.attachPermissions(["s3"]);

attachPermissionsToRoute

attachPermissionsToRoute(routeKey, permissions)

Parameters

Attaches the given list of permissions to a specific route. This allows that function to access other AWS resources.

const api = new Api(stack, "Api", {
routes: {
"GET /notes": "src/list.main",
},
});

api.attachPermissionsToRoute("GET /notes", ["s3"]);

bind

bind(constructs)

Parameters

  • constructs Array<SSTConstruct>

Binds the given list of resources to all the routes.

api.bind([STRIPE_KEY, bucket]);

bindToRoute

bindToRoute(routeKey, constructs)

Parameters

  • routeKey string
  • constructs Array<SSTConstruct>

Binds the given list of resources to a specific route.

const api = new Api(stack, "Api", {
routes: {
"GET /notes": "src/list.main",
},
});

api.bindToRoute("GET /notes", [STRIPE_KEY, bucket]);

getFunction

getFunction(routeKey)

Parameters

  • routeKey string

Get the instance of the internally created Function, for a given route key where the routeKey is the key used to define a route. For example, GET /notes.

const api = new Api(stack, "Api", {
routes: {
"GET /notes": "src/list.main",
},
});

const listFunction = api.getFunction("GET /notes");

setCors

setCors(cors)

Parameters

Binds the given list of resources to a specific route.

const api = new Api(stack, "Api");

api.setCors({
allowMethods: ["GET"],
});

ApiCorsProps

allowCredentials?

Type : boolean

Default : false

Specifies whether credentials are included in the CORS request.

allowHeaders?

Type : Array<string>

Default : Allow all headers.

The collection of allowed headers.

// Allow all headers
allowHeaders: ["*"]

// Allow specific headers
allowHeaders: ["Accept", "Content-Type", "Authorization"]

allowMethods?

Type : Array<"GET" | "PUT" | "HEAD" | "POST" | "DELETE" | "ANY" | "PATCH" | "OPTIONS">

Default : Allow all methods.

The collection of allowed HTTP methods.

// Allow all methods
allowMethods: ["ANY"]

// Allow specific methods
allowMethods: ["GET", "POST"]

allowOrigins?

Type : Array<string>

Default : Allow all origins.

The collection of allowed origins.

// Allow all origins
allowOrigins: ["*"]

// Allow specific origins. Note that the url protocol, ie. "https://", is required.
allowOrigins: ["https://domain.com"]

exposeHeaders?

Type : Array<string>

Default : No expose headers are allowed.

The collection of exposed headers.

maxAge?

Type : ${number} second | ${number} seconds | ${number} minute | ${number} minutes | ${number} hour | ${number} hours | ${number} day | ${number} days

Default : No caching

Specify how long the results of a preflight response can be cached

maxAge: "1 day"

ApiDomainProps

domainName?

Type : string

The domain to be assigned to the API endpoint (ie. api.domain.com)

hostedZone?

Type : string

The hosted zone in Route 53 that contains the domain. By default, SST will look for a hosted zone by stripping out the first part of the domainName that's passed in. So, if your domainName is api.domain.com. SST will default the hostedZone to domain.com.

isExternalDomain?

Type : boolean

Set this option if the domain is not hosted on Amazon Route 53.

path?

Type : string

The base mapping for the custom domain. For example, by setting the domainName to api.domain.com and the path to v1, the custom domain URL of the API will become https://api.domain.com/v1/. If the path is not set, the custom domain URL will be https://api.domain.com. Note the additional trailing slash in the former case.

cdk.certificate?

Type : ICertificate

Override the internally created certificate

cdk.domainName?

Type : IDomainName

Override the internally created domain name

cdk.hostedZone?

Type : IHostedZone

Override the internally created hosted zone

ApiAlbRouteProps

Specify a route handler that forwards to an ALB

api.addRoutes(stack, {
"GET /notes/{id}": {
type: "alb",
cdk: {
albListener: listener,
}
}
});

authorizationScopes?

Type : Array<string>

authorizer?

Type : "none" | "iam" | string

type

Type : "alb"

cdk.albListener

Type : IApplicationListener

The listener to the application load balancer used for the integration.

cdk.integration?

Type : HttpAlbIntegrationProps

ApiJwtAuthorizer

Specify a JWT authorizer and configure additional options.

new Api(stack, "Api", {
authorizers: {
Authorizer: {
type: "jwt",
userPool: {
issuer: "https://abc.us.auth0.com",
audience: ["123"],
},
},
},
});

identitySource?

Type : Array<string>

Default : ["$request.header.Authorization"]

The identity source for which authorization is requested.

jwt.audience

Type : Array<string>

A list of the intended recipients of the JWT.

jwt.issuer

Type : string

The base domain of the identity provider that issues JWT.

name?

Type : string

The name of the authorizer.

type

Type : "jwt"

String literal to signify that the authorizer is JWT authorizer.

cdk.authorizer

Type : HttpJwtAuthorizer

This allows you to override the default settings this construct uses internally to create the authorizer.

ApiAccessLogProps

destinationArn?

Type : string

format?

Type : string

retention?

Type : "one_day" | "three_days" | "five_days" | "one_week" | "two_weeks" | "one_month" | "two_months" | "three_months" | "four_months" | "five_months" | "six_months" | "one_year" | "thirteen_months" | "eighteen_months" | "two_years" | "five_years" | "six_years" | "seven_years" | "eight_years" | "nine_years" | "ten_years" | "infinite"

ApiHttpRouteProps

Specify a route handler that forwards to another URL

api.addRoutes(stack, {
"GET /notes/{id}": {
type: "url",
url: "https://example.com/notes/{id}",
}
});

authorizationScopes?

Type : Array<string>

authorizer?

Type : "none" | "iam" | string

type

Type : "url"

This is a constant

url

Type : string

The URL to forward to

cdk.integration

Type : HttpUrlIntegrationProps

Override the underlying CDK integration

ApiLambdaAuthorizer

Specify a Lambda authorizer and configure additional options.

new Api(stack, "Api", {
authorizers: {
Authorizer: {
type: "lambda",
function: new Function(stack, "Authorizer", {
handler: "test/lambda.handler",
}),
},
},
});

function?

Type : Function

Used to create the authorizer function

identitySource?

Type : Array<string>

Default : ["$request.header.Authorization"]

The identity source for which authorization is requested.

name?

Type : string

The name of the authorizer.

responseTypes?

Type : Array<"iam" | "simple">

Default : ["iam"]

The types of responses the lambda can return. If simple is included then response format 2.0 will be used.

resultsCacheTtl?

Type : ${number} second | ${number} seconds | ${number} minute | ${number} minutes | ${number} hour | ${number} hours | ${number} day | ${number} days

Default : Not cached

The amount of time the results are cached.

type

Type : "lambda"

String literal to signify that the authorizer is Lambda authorizer.

cdk.authorizer

Type : HttpLambdaAuthorizer

This allows you to override the default settings this construct uses internally to create the authorizer.

ApiPothosRouteProps

Specify a route handler that handles GraphQL queries using Pothos

// Change
api.addRoutes(stack, {
"POST /graphql": {
type: "pothos",
function: {
handler: "functions/graphql/graphql.ts",
},
schema: "backend/functions/graphql/schema.ts",
output: "graphql/schema.graphql",
commands: [
"./genql graphql/graphql.schema graphql/
]
}
})

// To
api.addRoutes(stack, {
"POST /graphql": {
type: "graphql",
function: {
handler: "functions/graphql/graphql.ts",
},
pothos: {
schema: "backend/functions/graphql/schema.ts",
output: "graphql/schema.graphql",
commands: [
"./genql graphql/graphql.schema graphql/
]
}
}
})

authorizationScopes?

Type : Array<string>

authorizer?

Type : "none" | "iam" | string

commands?

Type : Array<string>

Commands to run after generating schema. Useful for code generation steps

function

Type : string | Function | FunctionProps

The function definition used to create the function for this route. Must be a graphql handler

output?

Type : string

File to write graphql schema to

schema?

Type : string

Path to pothos schema

type

Type : "pothos"

ApiGraphQLRouteProps

Specify a route handler that handles GraphQL queries using Pothos

api.addRoutes(stack, {
"POST /graphql": {
type: "graphql",
function: {
handler: "functions/graphql/graphql.ts",
},
pothos: {
schema: "backend/functions/graphql/schema.ts",
output: "graphql/schema.graphql",
commands: [
"./genql graphql/graphql.schema graphql/
]
}
}
})

authorizationScopes?

Type : Array<string>

authorizer?

Type : "none" | "iam" | string

function

Type : string | Function | FunctionProps

The function definition used to create the function for this route. Must be a graphql handler

pothos.commands?

Type : Array<string>

Commands to run after generating schema. Useful for code generation steps

pothos.output?

Type : string

File to write graphql schema to

pothos.schema?

Type : string

Path to pothos schema

type

Type : "graphql"

ApiFunctionRouteProps

Specify a function route handler and configure additional options

api.addRoutes(stack, {
"GET /notes/{id}": {
type: "function",
function: "src/get.main",
payloadFormatVersion: "1.0",
}
});

authorizationScopes?

Type : Array<string>

authorizer?

Type : "none" | "iam" | string

function?

Type : string | Function | FunctionProps

The function definition used to create the function for this route.

payloadFormatVersion?

Type : "1.0" | "2.0"

Default : "2.0"

The payload format version for the route.

type?

Type : "function"

cdk.function?

Type : IFunction

Use an existing Lambda function.

ApiUserPoolAuthorizer

Specify a user pool authorizer and configure additional options.

new Api(stack, "Api", {
authorizers: {
Authorizer: {
type: "user_pool",
userPool: {
id: userPool.userPoolId,
clientIds: [userPoolClient.userPoolClientId],
},
},
},
});

identitySource?

Type : Array<string>

Default : ["$request.header.Authorization"]

The identity source for which authorization is requested.

name?

Type : string

The name of the authorizer.

type

Type : "user_pool"

String li any shot and having even a miniscule shotteral to signify that the authorizer is user pool authorizer.

userPool.clientIds?

Type : Array<string>

The ids of the user pool clients to use for authorization.

userPool.id

Type : string

The id of the user pool to use for authorization.

userPool.region?

Type : string

The AWS region of the user pool.

cdk.authorizer

Type : HttpUserPoolAuthorizer

This allows you to override the default settings this construct uses internally to create the authorizer.