Ktor & REST API

product: jvm/app

settings:
  ktor: enabled
  kotlin:
    serialization: enabled
  jvm:
    mainClass: nl.monsterbattles.api.ApplicationKt

dependencies:
  - $ktor.server.core
  - $ktor.server.netty
  - $ktor.server.config.yaml
  - ch.qos.logback:logback-classic:1.5.38
  - $ktor.server.contentNegotiation
  - $ktor.serialization.kotlinx.json
  - $ktor.server.statusPages

test-dependencies:
  - $ktor.server.testHost

package nl.monsterbattles.api.features.monsters.model

enum class Element { FIRE, WATER, WIND }

package nl.monsterbattles.api.features.monsters.model

data class Stats(val hp: Int, val attack: Int, val defense: Int, val speed: Int) {
    init {
        require(hp > 0) { "HP must be positive" }
        require(attack >= 0) { "Attack cannot be negative" }
        require(defense >= 0) { "Defense cannot be negative" }
        require(speed >= 0) { "Speed cannot be negative" }
    }
}

package nl.monsterbattles.api.features.monsters.model

class Monster(val id: Int, val name: String, val element: Element, val stats: Stats) {
    init {
        require(id > 0) { "ID must be positive" }
        require(name.isNotBlank()) { "Name is required" }
    }
}

package nl.monsterbattles.api.features.monsters.dto

import kotlinx.serialization.Serializable
import nl.monsterbattles.api.features.monsters.model.*

@Serializable
data class CreateMonsterRequest(
    val name: String,
    val element: Element,
    val hp: Int,
    val attack: Int,
    val defense: Int,
    val speed: Int
)

@Serializable
data class UpdateMonsterRequest(
    val name: String,
    val element: Element,
    val hp: Int,
    val attack: Int,
    val defense: Int,
    val speed: Int
)

@Serializable
data class MonsterResponse(
    val id: Int,
    val name: String,
    val element: Element,
    val hp: Int,
    val attack: Int,
    val defense: Int,
    val speed: Int
)

fun Monster.toResponse() = MonsterResponse(
    id, name, element, stats.hp, stats.attack, stats.defense, stats.speed
)

fun CreateMonsterRequest.toStats() = Stats(hp, attack, defense, speed)
fun UpdateMonsterRequest.toStats() = Stats(hp, attack, defense, speed)

package nl.monsterbattles.api.features.monsters.repository

import nl.monsterbattles.api.features.monsters.model.*

interface MonsterRepository {
    fun findAll(): List<Monster>
    fun findById(id: Int): Monster?
    fun create(name: String, element: Element, stats: Stats): Monster
    fun update(id: Int, name: String, element: Element, stats: Stats): Monster?
    fun delete(id: Int): Boolean
}

package nl.monsterbattles.api.features.monsters.repository

import nl.monsterbattles.api.features.monsters.model.*

class InMemoryMonsterRepository : MonsterRepository {
    private val monsters = linkedMapOf<Int, Monster>()
    private var nextId = 1

    init {
        create("Pyron", Element.FIRE, Stats(100, 30, 10, 110))
        create("Aquara", Element.WATER, Stats(110, 25, 12, 95))
    }

    override fun findAll(): List<Monster> = monsters.values.toList()
    override fun findById(id: Int): Monster? = monsters[id]

    override fun create(name: String, element: Element, stats: Stats): Monster {
        val monster = Monster(nextId++, name, element, stats)
        monsters[monster.id] = monster
        return monster
    }

    override fun update(id: Int, name: String, element: Element, stats: Stats): Monster? {
        if (id !in monsters) return null
        val monster = Monster(id, name, element, stats)
        monsters[id] = monster
        return monster
    }

    override fun delete(id: Int): Boolean = monsters.remove(id) != null
}

package nl.monsterbattles.api.features.monsters

import nl.monsterbattles.api.features.monsters.model.*
import nl.monsterbattles.api.features.monsters.dto.*
import nl.monsterbattles.api.features.monsters.repository.MonsterRepository

class MonsterNotFoundException(id: Int) : RuntimeException("Monster $id does not exist")

class MonsterService(private val repository: MonsterRepository) {
    fun list(): List<MonsterResponse> = repository.findAll().map(Monster::toResponse)

    fun get(id: Int): MonsterResponse =
        (repository.findById(id) ?: throw MonsterNotFoundException(id)).toResponse()

    fun create(request: CreateMonsterRequest): MonsterResponse {
        val name = request.name.trim()
        require(name.isNotBlank()) { "Name is required" }
        return repository.create(name, request.element, request.toStats()).toResponse()
    }

    fun update(id: Int, request: UpdateMonsterRequest): MonsterResponse {
        val name = request.name.trim()
        require(name.isNotBlank()) { "Name is required" }
        val updated = repository.update(id, name, request.element, request.toStats())
            ?: throw MonsterNotFoundException(id)
        return updated.toResponse()
    }

    fun delete(id: Int) {
        if (!repository.delete(id)) throw MonsterNotFoundException(id)
    }
}

package nl.monsterbattles.api.common

import kotlinx.serialization.Serializable

@Serializable
data class ApiError(val code: String, val message: String)

package nl.monsterbattles.api.features.monsters

import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.plugins.BadRequestException
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import nl.monsterbattles.api.features.monsters.dto.*

fun Route.monsterRoutes(service: MonsterService) {
    route("/monsters") {
        get {
            call.respond(service.list())
        }
        get("/{id}") {
            val id = call.parameters["id"]?.toIntOrNull()
                ?: throw BadRequestException("Invalid monster ID")
            require(id > 0) { "ID must be positive" }
            call.respond(service.get(id))
        }
        post {
            val request = call.receive<CreateMonsterRequest>()
            val created = service.create(request)
            call.response.header(HttpHeaders.Location, "/monsters/${created.id}")
            call.respond(HttpStatusCode.Created, created)
        }
        put("/{id}") {
            val id = call.parameters["id"]?.toIntOrNull()
                ?: throw BadRequestException("Invalid monster ID")
            require(id > 0) { "ID must be positive" }
            call.respond(service.update(id, call.receive<UpdateMonsterRequest>()))
        }
        delete("/{id}") {
            val id = call.parameters["id"]?.toIntOrNull()
                ?: throw BadRequestException("Invalid monster ID")
            require(id > 0) { "ID must be positive" }
            service.delete(id)
            call.respond(HttpStatusCode.NoContent)
        }
    }
}

package nl.monsterbattles.api.config

import io.ktor.http.*
import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.application.*
import io.ktor.server.plugins.BadRequestException
import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.server.plugins.statuspages.*
import io.ktor.server.response.*
import kotlinx.serialization.SerializationException
import nl.monsterbattles.api.common.ApiError
import nl.monsterbattles.api.features.monsters.MonsterNotFoundException

fun Application.configurePlugins() {
    install(ContentNegotiation) { json() }
    install(StatusPages) {
        exception<MonsterNotFoundException> { call, cause ->
            call.respond(HttpStatusCode.NotFound, ApiError("MONSTER_NOT_FOUND", cause.message ?: "Monster not found"))
        }
        exception<IllegalArgumentException> { call, cause ->
            call.respond(HttpStatusCode.BadRequest, ApiError("INVALID_INPUT", cause.message ?: "Invalid input"))
        }
        exception<BadRequestException> { call, _ ->
            call.respond(HttpStatusCode.BadRequest, ApiError("INVALID_REQUEST", "Invalid request"))
        }
        exception<SerializationException> { call, _ ->
            call.respond(HttpStatusCode.BadRequest, ApiError("INVALID_JSON", "Invalid JSON"))
        }
        exception<Throwable> { call, cause ->
            environment.log.error("Unhandled request failure", cause)
            call.respond(HttpStatusCode.InternalServerError, ApiError("INTERNAL_ERROR", "Internal server error"))
        }
    }
}

package nl.monsterbattles.api

import io.ktor.server.application.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.routing.*
import nl.monsterbattles.api.config.configurePlugins
import nl.monsterbattles.api.features.monsters.*
import nl.monsterbattles.api.features.monsters.repository.InMemoryMonsterRepository

fun Application.module() {
    configurePlugins()
    val repository = InMemoryMonsterRepository()
    val service = MonsterService(repository)
    routing { monsterRoutes(service) }
}

fun main() {
    embeddedServer(Netty, host = "0.0.0.0", port = 8080) {
        module()
    }.start(wait = true)
}

@base = http://localhost:8080

### List all
GET {{base}}/monsters
Accept: application/json

### Get Pyron
GET {{base}}/monsters/1
Accept: application/json

### Create Zephyra (receives ID 3)
POST {{base}}/monsters
Content-Type: application/json

{"name":"Zephyra","element":"WIND","hp":90,"attack":27,"defense":9,"speed":120}

### Update Zephyra
PUT {{base}}/monsters/3
Content-Type: application/json

{"name":"Zephyra","element":"WIND","hp":90,"attack":28,"defense":9,"speed":120}

### Delete Zephyra
DELETE {{base}}/monsters/3

### Deleted item is gone
GET {{base}}/monsters/3

GET /monsters    -> 200 OK, two seeded monsters
GET /monsters/1  -> 200 OK, Pyron
POST /monsters   -> 201 Created + Location: /monsters/3
PUT /monsters/3  -> 200 OK, attack=28
DELETE /monsters/3 -> 204 No Content
GET /monsters/3  -> 404 Not Found + ApiError

@base = http://localhost:8080

### Bad ID format
GET {{base}}/monsters/abc

### Missing monster
GET {{base}}/monsters/999

### Invalid stats
POST {{base}}/monsters
Content-Type: application/json

{"name":"Broken","element":"FIRE","hp":0,"attack":5,"defense":2,"speed":5}

### Missing required JSON field
POST {{base}}/monsters
Content-Type: application/json

{"name":"Incomplete"}

400 INVALID_REQUEST
404 MONSTER_NOT_FOUND
400 INVALID_INPUT
400 INVALID_REQUEST (request decoding)