https://github.com/conduktor/scala-api-template

Example Scala API to bootstrap new projects
https://github.com/conduktor/scala-api-template

best-practices kafka scala template zio

Last synced: 7 months ago
JSON representation

Example Scala API to bootstrap new projects

• Host: GitHub
• URL: https://github.com/conduktor/scala-api-template
• Owner: conduktor
• License: apache-2.0
• Created: 2021-03-17T12:31:31.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2023-03-04T00:12:57.000Z (over 2 years ago)
• Last Synced: 2023-03-05T15:47:17.023Z (over 2 years ago)
• Topics: best-practices, kafka, scala, template, zio
• Language: Scala
• Homepage: https://www.conduktor.io
• Size: 348 KB
• Stars: 47
• Watchers: 12
• Forks: 11
• Open Issues: 17
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


# Conduktor's Scala API template

A template for writing Restful APIs we use at Conduktor.

## Requirements 

The requirements are:

- store data into Postgres

- handle Postgres schema and schema migration programmatically

- expose domain logic via a RESTful API

- describe the RESTful API using OpenAPI standard

- secure the RESTful API with JWT using auth0 service (https://auth0.com) but avoid vendor lock-in

- use only non-blocking technologies and implement only stateless services to handle high-scale workload

- leverage Scala type-system and hexagonal architecture to minimize the testing requirements

- enable testing at every layer: domain logic, end-to-end, data-access, RESTful API, integration of various layer combinations

- enforce green tests and style conformance using Github actions

- generate a docker image using Github actions and push it to a repository

- allows developing proprietary software

## Tech

This is the list of technologies we chose to implement our requirements:

- http4s (https://http4s.org/) for HTTP implementation, APL v2 license

- circe (https://circe.github.io/circe/) for JSON serialization, APL v2 license

- tapir (https://tapir.softwaremill.com) for RESTful API description, APL v2 license

- skunk (https://tpolecat.github.io/skunk/) for async (non-jdbc) Postgres access, MIT license

- flyway (https://flywaydb.org/) for database schema handling, APL v2 license

- zio (https://zio.dev/) for effect, streaming, logging, config and tests, APL v2 license

- JWT validation using auth0-provided Java library, MIT license

- refined (https://github.com/fthomas/refined) for defining value objects constraints, MIT license

- newtype (https://github.com/estatico/scala-newtype) for generating value objects with no runtime cost, APL v2 license

- sbt-native-packager (https://sbt-native-packager.readthedocs.io) for docker image generation, BSD-2-Clause License

## Development flow

- create branches from main

- merge into main to release Staging via Github action

- tag main to release Prod via Github action

The stack is deployed on Google Cloud (Cloud Run + Cloud SQL)

## Migration

Database provisioning / migration is done via [flyway](https://flywaydb.org/)

The migrations are applied at application start to ensure the database is up-to-date with current running code.

## Auth

Auth is a JWT validation + data extraction, against an auth0 tenant.

We retrieve the exposed public key from auth0, and use it to validate and decode the bearer token provided in the authorization header 

## ISSUES

 - Intellij can't type properly skunk's "sql" StringOps macro,

using Metals is therefore recommended when dealing with repositories

## TODOS

- use domain-specific errors

- add streaming endpoints examples (paginated, websocket)