FAF API

This is the official FAForever API. Amongst others, the API offers the following functionality:

• User management (registration, password reset, etc.)
• JSON-API compliant REST API for lots of community data (i.e. map, mod & replay vault, game statistics, etc.)
• Leaderboards
• Clan management
• Vault upload functionality
• Internal FAF featured mod deployments
• Challonge proxy

How to run

Setup database

The application requires a database scheme in the right version. To create this database please checkout the project faf-stack, open a shell terminal (git bash on Windows) and run the script scripts/init-db.sh. This will setup the database in the latest version and configure the users for you.

From source

In order to run the application from source code:

1. Clone the repository
2. Import the project into IntelliJ. For some reason, IntelliJ deletes launch configurations after import. Please revert such deleted files first (Version Control (Alt+F9) -> Local Changes)
3. Configure your JDK if you haven't already
4. Make sure you have the IntelliJ Lombok plugin installed
5. Set up a FAF database.
6. Launch FafApiApplication

From binary

Given the number of required configuration values, it's easiest to run the API using faf-stack:

docker-compose up -d faf-java-api

Database dependency

Due to potential issues with Hibernate, the application checks on startup if the flyway migration version matches the expected version and otherwise fails to boot.

• To increment the db version you need to change it in two places:
  • application.yml: faf-api.database.schema-version (just an integer of the version)
  • .github/workflows/build.yaml: Global variable FAF_DB_VERSION (git tag of the db release, usually prefixed with a v)
• In some cases it might make sense to override the required version on the server. Use the env variable DATABASE_SCHEMA_VERSION

Sample routes

• API documentation
• List event definitions
• List 5 maps with more than 8 players
• List UI mods, sorted by last updated ascending
• List all players
• List events of players
• List replays

Technology Stack

This project uses:

• Java 17 as the programming language
• Spring Boot as a framework
• Hibernate ORM as ORM mapper
• Elide with RSQL filters to serve JSON-API conform data
• Gradle as a build automation tool
• Docker to deploy and run the application
• Swagger as an API documentation tool