Feature for Ktor implementing Rfc7807
It is inspired by Zalando's Problem library.
com.tyntec:ktor-problem:0.7
In your ktor application simply add
install(RFC7807Problems) {
}
Ktor Problem comes along with support of Jackson and Gson for serialization.
The configuration is similar to the Content Negotation feature of Ktor.
Jackson
install(Problems) {
jackson {}
}
Gson
install(Problems) {
gson {}
}
custom one
Ktor Problem allows you to customize the serialization to json completely. This is covered in the section below
The application will catch all exceptions and wrap them in a Problems object, like this
{
"status" : 500,
"title" : Internal Server Error,
"instance" : "<URI path>",
"detail" : "<Exception message>"
}
Problems allows you to configure the default behavior as well a exception specific.
Exception specific configurations are done via the configuration method
exception<Throwable> { context -> ... }
The context provides access to the ApplicationCall
and the original exception
Like in this example
exception<IllegalArgumentException> {ctx ->
instance = ctx.call.request.path()
statusCode = HttpStatusCode.BadRequest
detail = ctx.throwable.message
type = "https://api.tyntec.com/error_codes/BadRequest.html"
}
The default behavior is configured by the default
configuration method.
It has the access to the same context
object as the exception specific handling.
Logging of caught exceptions can be controlled via exceptionLogging
. It supports at the moment
- OFF - logging is completly turned off
- SHORT - Only the http method, path and exception message is logged
- FULL - Http method, path and the whole stack trace is logged
The library intercepts in the default setting non successful http status codes and put's them into the problem structure.
This behavior can be turned of by the toggle enableAutomaticResponseConversion
.
Provide configurations that handle all exceptions can be cumbersome and decrease the clarity of the configuration.
Ktor Problem admits this by defining the interface Problem
and the super class ThrowableProblem
.
The latter is a convenience implementation of Problem
interface.
When throwing an exception that implements the interface or extends the ThrowableProblem
class, Ktor Problem detects
this and takes the properties from the implementing class to generate the error response.
Note : Jackson is currently the only converter which suppress the publication of Throwable details, like stacktrace etc. pp. . Support for GSon is planned but not finished.
This business exception
class TestBusinessException(
var businessDetail : String
) : ThrowableProblem(
type = "Any type",
statusCode = HttpStatusCode.BadRequest,
detail = "DefaultProblem to be thrown",
title = "Awesome title"
)
is translated to
{
"businessDetail":"a test detail",
"type":"Any type",
"detail":"DefaultProblem to be thrown",
"instance":null,
"title":"Awesome title",
"status":400
}
In order to provider your custom json problemConverter you need to implement the ProblemConverter
interface.
Afterwards enable it via
install(RC7807Problems) {
converter{MyConverter()}
}