🏆 Leaderboard API
Introduction
This project is a web API designed to manage player rankings during a tournament.
Key Features
- Add a new player
- Update a player's score
- Retrieve player details (username, points, and ranking)
- Retrieve players sorted by rank
- Reset the tournament (delete all players)
⚙️ Technologies
Category | Technology |
---|---|
Database | DynamoDB |
Backend | Kotlin (2.1.10) |
Framework | Ktor (2.3.13) |
Dependency Injection | Koin (4.0.2) |
⚖️ Technical choices
Exception handling
Exception handling with the ktor-server-status-pages
dependency. Mapping of custom exceptions to HTTP codes.
Tests
Use of Junit 5.
Use of MockK to facilitate mocking with Kotlin.
Use of test containers with localstack to start databases on the fly for integration and end-to-end tests.
Logs
Use of logback
and slf4j
to provide consistent logging with low coupling.
💻 Run the app locally
Prerequisites
To start the application locally, you need to have installed:
- Docker
- Maven
- Java (version 11+)
Start the database
Using the root folder of the project as the working directory, run the following command to start the database with Docker:
docker compose up -d
Start the app
Using the root folder of the project as the working directory, run the following command to start the app with Maven:
mvn clean compile exec:java
Explore the API
If you are using IntelliJ as your IDE, you can test the API using the .http
file located in src/main/resources/http
.
Alternatively, you can reference the HTTP requests from that file and use other tools like Postman, Insomnia, etc.
🧪 Tests
The tests can be run with the following command:
mvn clean test
🧹 Linting
This project uses Ktlint for linting.
IntelliJ Setup
If you are using IntelliJ, follow these steps:
- Install Ktlint via
File
>Settings
>Plugins
. - You may need to restart your IDE.
- Once Ktlint is installed, go to
File
>Settings
>Tools
>Ktlint
, then:- Enable Distract free mode.
- Check On save.
🚀 Before going to production
Better documentation
Adding an OpenAPI documentation would help to maintain the project.
Improving performances
In the current implementation the backend retrieves all the players from the database to rank them. Better performances could be achieved by ranking players at the database level and adding pagination.
Achieving a greater test coverage
Adding more unit tests, integration tests and end-to-end tests to achieve a greater test coverage is crucial to build a robust application.
Handling transactions
Handling transactions to avoid unwanted behaviours is necessary before moving to production.
Using credentials with the database
Adding credentials to access the database is crucial to improve security.
Proper CORS handling
In the current implementation, CORS is configured with broad permissions, allowing all hosts. Refining CORS rules will ensure that only trusted sources can interact with the API, reducing potential security risks.
Release pipeline
A release pipeline would ensure a reliable and efficient release process by automatically incrementing version numbers, building and tagging artifacts and pushing them on a registry. This could be done with Gitlab CI/CD and the Gitlab Registry.
Setting up a development and a production environment
In order to go to production there is a need to configure a development and a production environment. AWS could be used as a cloud provider and Terraform could be used to provision the instances with the managed service aws_dynamodb_table
for the database and an ECS or EKS for the backend.
Integration pipeline
A CI pipeline automates the process of building, testing, packaging, and deploying code, is crucial to ensure reliable integration and accelerate delivery. This could be done with Gitlab CI/CD.
Require authentication
In the current implementation, the API is open and does not require authentication, meaning anyone can send requests. However, to manage a leaderboard for a real tournament, it is necessary to implement authentication and role-based access control. This would allow for the designation of an administrator role and help prevent data manipulation. Typical tools would be the security dependency of Ktor.
Documentation on Ktor security configuration : Authentication and authorization in Ktor Server on Ktor's official documentation and Ktor Server Auth on Maven Repository.
Enabling alerting and monitoring
Alerting and monitoring is crucial for proactive issue detection. The project would benefit from having such tools before going to production. Typical tools would be Sentry, Datadog, Grafana, etc.