https://github.com/schwarzit/kotlin-rfc9457-problem-details
A Kotlin implementation of the RFC 9457 problem details format for handling HTTP API errors.
https://github.com/schwarzit/kotlin-rfc9457-problem-details
api json kotlin library openapi problem-details problem-details-for-http-apis rest rfc-9457
Last synced: 21 days ago
JSON representation
A Kotlin implementation of the RFC 9457 problem details format for handling HTTP API errors.
- Host: GitHub
- URL: https://github.com/schwarzit/kotlin-rfc9457-problem-details
- Owner: SchwarzIT
- License: apache-2.0
- Created: 2024-08-26T08:12:14.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-03-24T01:45:48.000Z (about 1 month ago)
- Last Synced: 2025-04-12T06:53:04.019Z (21 days ago)
- Topics: api, json, kotlin, library, openapi, problem-details, problem-details-for-http-apis, rest, rfc-9457
- Language: Kotlin
- Homepage:
- Size: 117 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Kotlin-RFC9457-Problem-Details
[](https://jobs.schwarz)
The `Kotlin-RFC9457-Problem-Details` library implements `application/problem+json` according to [RFC 9457](https://datatracker.ietf.org/doc/rfc9457/) in Kotlin. Problem-Details provides all necessary interfaces and builders to comply with the RFC.
## Features
- provides all necessary interfaces and serialisers to implement [RFC 9457](https://datatracker.ietf.org/doc/rfc9457/)
- provides a centralised approach to error objects to normalise REST APIs
- conforms to `application/problem+json`
## Installation
```kotlin
dependencies {
implementation("io.github.schwarzit:kotlin-rfc9457-problem-details:$problemDetailsVersion")
}
```
## Usage
The library offers several ways to use the problem object. There are some static constructors and a builder that makes it really easy to use.
We recommend using the library in combination with the `io.ktor:ktor-server-status-pages` when using Ktor.
### Status Pages
The following example uses the problem library in order to handle an `IllegalArgumentException` thrown by your application within the status pages handler.
`respondProblem` is used in order to set the content type to `application/problem+json`.
```kotlin
install(StatusPages) {
exception { call, cause ->
val httpStatus = HttpStatusCode.BadRequest
val problem = Problem.of(
httpStatus,
"problem/illegal-argument-error.html",
cause.message,
"https://example.org"
)
call.respondProblem(httpStatus, problem)
}
}
```
#### Serving Problem Types
Serving problem types can be easily done using the [static resources feature of ktor](https://ktor.io/docs/server-static-content.html#resources).
```kotlin
routing {
staticResources("/problem", "problem-details")
}
```
### Static constructors
The library delivers two static constructors for easy use.
If you don't have defined a type yet, but want to conform to the standard the following constructor can be used:
```kotlin
Problem.of(HttpStatusCode.BadRequest)
```
This will produce in the following json
```json
{
"type": "about:blank",
"status": 400,
"title": "Bad Request"
}
```
If you want to add some more information and a problem type the following can be used:
```kotlin
Problem.of(
HttpStatusCode.BadRequest,
"problem/illegal-argument-error.html",
"Parameter is mandatory",
"https://example.org"
)
```
This will produce in the following json
```json
{
"type": "https://example.org/problem/illegal-argument-error.html",
"status": 400,
"title": "Bad Request",
"detail": "Parameter is mandatory"
}
```
### Builder
If you need more flexibility this library also offers a builder that makes it possible to set all properties of the standard and add more if needed (also like the standard defines).
The builder can be used as follows:
```kotlin
val problem = problem {
type("problem/illegal-argument-error.html", "https://example.org")
status = 400
title = "Bad Request"
detail = "Invalid parameters were handed over"
instance = "Instance reference"
extension("errors", listOf("Name parameter is mandatory", "First name contains invalid characters"))
}
```
This will produce in the following json
```json
{
"type": "https://example.org/problem/illegal-argument-error.html",
"status": 400,
"title": "Bad Request",
"detail": "Invalid parameters were handed over",
"instance": "Instance reference",
"errors": [
"Name parameter is mandatory",
"First name contains invalid characters"
]
}
```
## Dependencies
- kotlin
- ktor serialization kotlinx json
- ktor server core
- kotest
- kotlin serialization plugin