Ktor Server

Ktor Server is a framework for building asynchronous server-side applications. Akkurate provides an integration to automatically validate incoming data.

Installation

Before using Akkurate with Ktor, you need to add the following dependency to your Gradle script:

Add the Akkurate plugin for Ktor

implementation("dev.nesk.akkurate:akkurate-ktor-server:0.11.0")

Validate on receive

Take the following route that deserializes the body to a Book instance:

routing {
    post("/books") {
        val book = call.receive<Book>()
        call.respond(book.title)
    }
}

We want to make sure the book title is always filled. Here's the data class and its validator:

@Validate
@Serializable
data class Book(val title: String)

val validateBook = Validator<Book> {
    title.isNotEmpty()
}

install(Akkurate)
install(ContentNegotiation) { json() }
install(RequestValidation) {
    registerValidator(validateBook)
}

When deserializing the request body, the Book instance is automatically validated:

curl 127.0.0.1:8080/books -v \
    --header 'Content-Type: application/json' \
    --data '{"title": ""}'

// HTTP/1.1 422 Unprocessable Entity
// Content-Type: application/problem+json

{
  "status": 422,
  "fields": [
    {
      "message": "Must not be empty",
      "path": "title"
    }
  ],
  "type": "https://akkurate.dev/validation-error",
  "title": "The payload is invalid",
  "detail": "The payload has been successfully parsed, but the server is unable to accept it due to validation errors."
}

Customize the response

A default response, based on the RFC 9457 (Problem Details for HTTP APIs), is returned when the validation fails.

You can customize its status and Content-Type header:

install(Akkurate) {
    status = HttpStatusCode.BadRequest
    contentType = ContentType.Application.Json
}

If you need a different payload, you can override the whole response builder:

install(Akkurate) {
    buildResponse { call, violations ->
        call.respond(
            HttpStatusCode.BadRequest,
            violations.byPath.toString()
        )
    }
}

Last modified: 19 December 2024