RealWorld spec and API.Kotlin + http4k codebase containing real world examples (CRUD, auth, advanced patterns, etc) that adheres to the
This codebase was created to demonstrate a fully fledged fullstack application built with Kotlin + http4k + Exposed including CRUD operations, authentication, routing, pagination, and more.
For more information on how to this works with other frontends/backends, head over to the RealWorld repo.
How it works
The application was made mainly to demo the functionality of http4k framework together with exposed.
The application was built with:
- Kotlin as programming language.
- http4k as web framework.
- h2, an embedded lightweight database, as data storage. Although the application can support all the databases supported by exposed.
- exposed to access database and build typesafe SQL queries.
- jsonwebtoken to handle JSON Web Tokens for request authorization.
- log4j for proper logging in the application.
- kotlintest as testing framework for kotlin.
- mockk as mocking library for Kotlin.
Basically, the application has four main parts:
mainfunction which instantiates all the services and handlers and connects them together, then starts the server.
Routerclass which handles the translation of 1. http requests to request handler calls and 2. handler results to http responses. Authorization logic is also implemented in this class.
handlerpackage which contains a class for every request handler. Handlers are classes with one method (
invoke) which handles the request. This package contains the whole business logic of the application. Handlers have access to data layer.
ConduitRepositoryclass which is responsible for building database queries. In order to communicate to database, a class called
ConduitTransactionManagerImplis needed. this class has one method (
tx) which connects to database and opens a transaction to communicate with database.
txaccepts an anonymous function while provides an instance of
ConduitRepositoryas a receiver.
+ config/ Application config as simple data classes + handler/ All handler classes which describe business logic of the application + model/ domain model and dtos + repository/ table definitions, typesafe database creation scripts and classes to communicate with database + util/ utility classes such as request filters, serialization/deserialization functions and jwt utility functions + Main.kt File containing main function + Router.kt File containing Router class responsible for handling http server communication
The application currently uses H2 embedded database. The connection is defined in
config/local.kt. If you want to change the database you need to provide the correct dependency for the driver and change the configuration.
You can run
./gradlew test to run all the tests. A test logger gradle plugin (
com.adarshr.test-logger) has used to render the test beautifully in console.
There are a couple of unit tests for handlers but not for all of them (contributions welcome!).
There are integration tests to cover all the cases of the postman test file.
You need Java 11 installed.
Build and run tests:
./gradlew clean build
Start the server:
The server will be available on
There are various ways to contribute to this project. Some of them are:
- Just clone the project and play with it! This is the purpose of this project.
- Create an issue if you find a bug or you have suggestions.
- Fix bugs, improve code or documentation.
- Write more tests for the project to increase the code coverage.
- Or look at the issue with help wanted label.