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 AwsLambdaIORuntime 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.19.0-M13"

To configure API Gateway and the Lambda function, you can use:

  • the AwsSamInterpreter which interprets tapir Endpoints into an AWS SAM template file
  • or the AwsTerraformInterpreter which interprets Endpoints into terraform configuration file.

Add one of the following dependencies:

"com.softwaremill.sttp.tapir" %% "tapir-aws-sam" % "0.19.0-M13"
"com.softwaremill.sttp.tapir" %% "tapir-aws-terraform" % "0.19.0-M13"

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 and runMain 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 and terraform 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.