A template for writing Restful APIs we use at Conduktor.
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
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
- 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)
Database provisioning / migration is done via flyway
The migrations are applied at application start to ensure the database is up-to-date with current running code.
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
- Intellij can't type properly skunk's "sql" StringOps macro, using Metals is therefore recommended when dealing with repositories
- use domain-specific errors
- add streaming endpoints examples (paginated, websocket)