Api
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. See the examples for more details.
Unlike the lower level Function
construct, the Api
construct doesn't directly extend a CDK construct, it wraps around a couple of them.
#
InitializerParameters
#
ExamplesThe Api
construct is designed to make it easy to get started it 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 configNote that, the route key can have extra spaces in between, they are just ignored.
#
Adding routesAdd routes after the API has been created.
#
Lazily adding routesCreate an empty Api construct and lazily add the routes.
#
Specifying function props for all the routesYou can extend the minimal config, to set some function props and have them apply to all the routes.
#
Using the full configIf you wanted to configure each Lambda function separately, you can pass in the ApiRouteProps
.
Note that, you can set the defaultFunctionProps
while using the function
per route. The function
will just override the defaultFunctionProps
. Except for the environment
property, which will be merged.
So in the above example, the GET /notes
function doesn't use the timeout
that is set in the defaultFunctionProps
. 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.
#
Configuring the Http ApiConfigure the internally created CDK Api
instance.
#
Importing an existing Http ApiOverride the internally created CDK HttpApi
instance.
#
Configuring the access log formatUse a CSV format instead of default JSON format.
#
Configuring CORSOverride the default behavior of allowing all methods, and only allow the GET method.
#
Configuring custom domainsYou can also configure the API with a custom domain. SST currently supports domains that are configured using Route 53. If your domains are hosted elsewhere, you can follow this guide to migrate them to Route 53.
#
Using the basic config#
Configuring with a wildcard#
Using the full config#
Mapping multiple APIs to the same domain#
Importing an existing API Gateway custom domain#
Importing an existing certificate#
Attaching permissionsYou can attach a set of permissions to all or some of the routes.
#
For the entire APIAllow the entire API to access S3.
#
For a specific routeAllow one of the routes to access S3.
#
Adding authYou can use IAM or JWT to add auth to your APIs.
#
Adding IAM authorizationYou can secure your APIs (and other AWS resources) by setting the defaultAuthorizationType
to AWS_IAM
and using the sst.Auth
construct.
#
Adding IAM authorization to a specific routeYou can also secure specific routes in your APIs by setting the authorizationType
to AWS_IAM
and using the sst.Auth
construct.
#
Adding JWT authorizationJWT allows authorized users to access your API. Note that, this is a different authorization method when compared to using AWS_IAM
and the sst.Auth
construct, which allows you to secure other AWS resources as well.
#
Adding JWT authorization to a specific routeYou can also secure specific routes using JWT by setting the authorizationType
per route.
Note that, setting a specific authorizer per route is not currently supported. It must be set for all the applicable routes as the defaultAuthorizer
.
#
Using Cognito User Pool as the JWT authorizerJWT can also use a Cognito User Pool as an authorizer.
#
Getting the function for a route#
PropertiesAn instance of Api
contains the following properties.
#
httpApiType: cdk.aws-apigatewayv2.HttpApi
The internally created CDK HttpApi
instance.
#
accessLogGroup?Type: cdk.aws-logs.LogGroup
If access logs are enabled, this is the internally created CDK LogGroup
instance.
#
apiGatewayDomain?Type: cdk.aws-apigatewayv2.DomainName
If custom domain is enabled, this is the internally created CDK DomainName
instance.
#
acmCertificate?Type: cdk.aws-certificatemanager.Certificate
If custom domain is enabled, this is the internally created CDK Certificate
instance.
#
MethodsAn instance of Api
contains the following methods.
#
getFunctionParameters
- routeKey
string
Returns
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
.
#
addRoutesParameters
- scope
cdk.Construct
- routes
{ [key: string]: FunctionDefinition | ApiRouteProps }
An associative array with the key being the route as a string and the value is either a FunctionDefinition
or the ApiRouteProps
.
#
attachPermissionsParameters
- permissions
Permissions
Attaches the given list of permissions to all the routes. This allows the functions to access other AWS resources.
Internally calls Function.attachPermissions
.
#
attachPermissionsToRouteParameters
routeKey
string
permissions
Permissions
Attaches the given list of permissions to a specific route. This allows that function to access other AWS resources.
Internally calls Function.attachPermissions
.
#
ApiProps#
routes?Type : { [key: string]: FunctionDefinition | ApiRouteProps }
, defaults to {}
The routes for this API. Takes an associative array, with the key being the route as a string and the value is either a FunctionDefinition
.
Or the ApiRouteProps.
#
cors?Type : boolean | cdk.aws-apigatewayv2.CorsPreflightOptions
, defaults to true
CORS support for all the endpoints in the API. Takes a boolean
value or a cdk.aws-apigatewayv2.CorsPreflightOptions
.
#
accessLog?Type : boolean | string | cdk.aws-apigatewayv2.CfnApiGatewayManagedOverrides.AccessLogSettingsProperty
, defaults to true
CloudWatch access logs for the API. Takes a boolean
value, a string
with log format, or a cdk.aws-apigatewayv2.CfnApiGatewayManagedOverrides.AccessLogSettingsProperty
.
#
customDomain?Type : string | ApiCustomDomainProps
The customDomain for this API. SST currently supports domains that are configured using Route 53. If your domains are hosted elsewhere, you can follow this guide to migrate them to Route 53.
Takes either the domain as a string.
Or the ApiCustomDomainProps.
#
httpApi?Type : cdk.aws-apigatewayv2.HttpApiProps | cdk.aws-apigatewayv2.HttpApi
Pass in a cdk.aws-apigatewayv2.HttpApi
value to override the default settings this construct uses to create the CDK HttpApi
internally.
Or, pass in an instance of the CDK cdk.aws-apigatewayv2.HttpApi
. SST will use the provided CDK HttpApi
instead of creating one internally.
#
defaultFunctionProps?Type : FunctionProps
, defaults to {}
The default function props to be applied to all the Lambda functions in the API. If the function
is specified for a route, these default values are overridden. Except for the environment
property, which will be merged.
#
defaultAuthorizationType?Type : ApiAuthorizationType
, defaults to ApiAuthorizationType.NONE
The authorization type for all the endpoints in the API. Set using ApiAuthorizationType
. Supports AWS IAM and JWT. Defaults to no authorization, ApiAuthorizationType.NONE
.
While both IAM and JWT allows you to secure your APIs. The IAM method together with the sst.Api
construct uses the Cognito Identity Pool. This allows you to secure other AWS resources as well.
On the other hand, the JWT method is for securing APIs specifically.
If you are just starting out, we recommend using the IAM method.
#
defaultAuthorizer?Type : cdk.aws-apigatewayv2-authorizers.HttpJwtAuthorizer | cdk.aws-apigatewayv2-authorizers.HttpUserPoolAuthorizer
The JWT authorizer for all the routes in the API. Currently, supports cdk.aws-apigatewayv2-authorizers.HttpJwtAuthorizer
or cdk.aws-apigatewayv2-authorizers.HttpUserPoolAuthorizer
.
#
defaultAuthorizationScopes?Type : string[]
, defaults to []
An array of scopes to include in the authorization when using JWT
as the defaultAuthorizationType
. These will be merged with the scopes from the attached authorizer.
For example, ["user.id", "user.email"]
.
#
defaultPayloadFormatVersion?Type : ApiPayloadFormatVersion
, defaults to ApiPayloadFormatVersion.V2
The payload format versions for all the endpoints in the API. Set using ApiPayloadFormatVersion
. Supports 2.0 and 1.0. Defaults to 2.0, ApiPayloadFormatVersion.V2
.
#
ApiRouteProps#
functionType : FunctionDefinition
The function definition used to create the function for this route.
#
authorizationType?Type : ApiAuthorizationType
The authorization type for a specific route. Set using ApiAuthorizationType
. Defaults to defaultAuthorizationType
.
#
authorizer?Type : cdk.aws-apigatewayv2-authorizers.HttpJwtAuthorizer | cdk.aws-apigatewayv2-authorizers.HttpUserPoolAuthorizer
The JWT authorizer for a specific route. Defaults to defaultAuthorizer
.
#
authorizationScopes?Type : string[]
An array of scopes to include in the authorization for a specific route. Defaults to defaultAuthorizationScopes
. If both defaultAuthorizationScopes
and authorizationScopes
are configured, authorizationScopes
is used. Instead of the union of both.
#
payloadFormatVersion?Type : ApiPayloadFormatVersion
The payload format versions for a specific route. Set using ApiPayloadFormatVersion
. Supports 2.0 and 1.0. Defaults to defaultPayloadFormatVersion
.
#
ApiCustomDomainProps#
domainNameType : string | cdk.aws-apigatewayv2.DomainName
The domain to be assigned to the API endpoint. Takes the custom domain as a string
(ie. api.domain.com
) or a cdk.aws-apigatewayv2.DomainName
.
Currently supports domains that are configured using Route 53.
#
hostedZone?Type : string | cdk.aws-route53.HostedZone
, defaults to the base domain
The hosted zone in Route 53 that contains the domain. Takes the name of the hosted zone as a string
or the hosted zone construct cdk.aws-route53.HostedZone
. 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
.
Set this option if SST cannot find the hosted zone in Route 53.
#
certificate?Type : cdk.aws-certificatemanager.Certificate
, defaults to undefined
The certificate for the domain. By default, SST will create a certificate with the domain name from the domainName
option.
Set this option if you have an existing certificate in AWS Certificate Manager you want to use.
#
path?Type : string
, defaults to undefined
The base mapping for the custom domain. For example, by setting the domainName
to api.domain.com
and path
to v1
, the custom domain URL for 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
.
caution
You cannot change the path once it has been set.
Note, if the path
was not defined initially, it cannot be defined later. If the path
was initially defined, it cannot be later changed to undefined. Instead, you'd need to remove the customDomain
option from the construct, deploy it. And then set it to the new path value.
#
ApiAuthorizationTypeAn enum with the following members representing the authorization types.
Member | Description |
---|---|
AWS_IAM | Used along with the sst.Auth construct to add Cognito Identity Pool and IAM authorization. |
JWT | Using JWT as an authorizer. |
NONE | No authorization type is set. |
For example, to use IAM, set sst.ApiAuthorizationType.AWS_IAM
.
#
ApiPayloadFormatVersionAn enum with the following members representing the payload format versions.
Member | Description |
---|---|
V2 | Version 2.0 of the payload is sent to the lambda handler. |
V1 | Version 1.0 of the payload is sent to the lambda handler. |
For example, to use V2, set sst.ApiPayloadFormatVersion.V2
.