Running using the AWS serverless stack¶
Tapir server endpoints can be packaged and deployed as an AWS Lambda function. To invoke the function, HTTP requests can be proxied through AWS API Gateway.
To configure API Gateway routes, and the Lambda function, tools like AWS SAM and Terraform can be used, to automate cloud deployments.
For an overview of how this works in more detail, see this blog post.
Serverless interpreters¶
To implement the Lambda function, a server interpreter is available, which takes tapir endpoints with associated server logic, and returns an AwsRequest => F[AwsResponse]
function. This is used in the AwsLambdaRuntime
to implement the Lambda loop of reading the next request, computing and sending the response.
Currently, only an interpreter integrating with cats-effect is available (AwsCatsEffectServerInterpreter
). To use, add the following dependency:
"com.softwaremill.sttp.tapir" %% "tapir-aws-lambda" % "0.18.0-M16"
To configure API Gateway and the Lambda function, you can use:
- the
AwsSamInterpreter
which interprets tapirEndpoints
into an AWS SAM template file - or the
AwsTerraformInterpreter
which interpretsEndpoints
into terraform configuration file.
Add one of the following dependencies:
"com.softwaremill.sttp.tapir" %% "tapir-aws-sam" % "0.18.0-M16"
"com.softwaremill.sttp.tapir" %% "tapir-aws-terraform" % "0.18.0-M16"
Examples¶
In our GitHub repository
you’ll find a LambdaApiExample
handler which uses AwsServerInterpreter
to route a hello endpoint along
with SamTemplateExample
and TerraformConfigExample
which interpret endpoints to SAM/Terraform configuration. Go
ahead and clone tapir project and select project awsExamples
from sbt shell.
Make sure you have AWS command line tools installed.
SAM¶
To try it out using SAM template you don’t need an AWS account.
- install AWS SAM command line tool
- run
assembly
task andrunMain sttp.tapir.serverless.aws.examples.SamTemplateExample
- open a terminal and in tapir root directory run
sam local start-api --warm-containers EAGER
That will create template.yaml
and start up AWS Api Gateway locally. Hello endpoint will be available
under curl http://127.0.0.1:3000/api/hello
. First invocation will take a while but subsequent ones will be faster
since the created container will be reused.
Terraform¶
To run the example using terraform you will need an AWS account, and an S3 bucket.
- install Terraform
- run
assembly
task - open a terminal in
tapir/serverless/aws/examples/target/jvm-2.13
directory. That’s where the fat jar is saved. You need to upload it into your s3 bucket. Using command line tools:aws s3 cp tapir-aws-examples.jar s3://{your-bucket}/{your-key}
. - Run
runMain sttp.tapir.serverless.aws.examples.TerraformConfigExample {your-aws-region} {your-bucket} {your-key}
- open terminal in tapir root directory, run
terraform init
andterraform apply
That will create api_gateway.tf.json
configuration and deploy Api Gateway and lambda function to AWS. Terraform will
output the url of the created API Gateway which you can call followed by /api/hello
path.
To destroy all the created resources run terraform destroy
.