https://github.com/t1/problem-details

Problem Details [RFC-9457] Java API, TCK, and implementations for JAX-RS and (currently not) Spring Boot
https://github.com/t1/problem-details

jax-rs microprofile microprofile-restclient rfc-7807 rfc7807 spring-boot

Last synced: about 1 month ago
JSON representation

Problem Details [RFC-9457] Java API, TCK, and implementations for JAX-RS and (currently not) Spring Boot

• Host: GitHub
• URL: https://github.com/t1/problem-details
• Owner: t1
• License: apache-2.0
• Created: 2019-12-13T10:51:01.000Z (almost 5 years ago)
• Default Branch: trunk
• Last Pushed: 2024-10-01T13:09:12.000Z (about 2 months ago)
• Last Synced: 2024-10-01T17:06:32.891Z (about 2 months ago)
• Topics: jax-rs, microprofile, microprofile-restclient, rfc-7807, rfc7807, spring-boot
• Language: Java
• Homepage:
• Size: 530 KB
• Stars: 16
• Watchers: 3
• Forks: 5
• Open Issues: 13
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

README

        
= Problem Detail image:https://maven-badges.herokuapp.com/maven-central/com.github.t1/problem-details/badge.svg[link=https://search.maven.org/artifact/com.github.t1/problem-details] image:https://github.com/t1/problem-details/actions/workflows/maven.yml/badge.svg[link=https://github.com/t1/problem-details/actions/workflows/maven.yml]

== Abstract

Map standard and custom exceptions to a http response body containing problem details as specified in https://datatracker.ietf.org/doc/html/rfc9457[RFC-9457] (formerly https://datatracker.ietf.org/doc/html/rfc7807[RFC-7807]).

Most things work out of the box: the `type` and `title` fields are derived from the exception class name; the `detail` field is the message of the exception; the `instance` field is a random UUID URN that is also logged together with the complete stack trace.

These defaults and the status code can be overridden with annotations.

I wrote a https://www.codecentric.de/wissens-hub/blog/rfc-7807-problem-details-with-spring-boot-and-jax-rs[blog] about this.

== Motivation

Getting a consistent error response format for a REST API is a common problem and allows clients to handle specific business errors. Getting some generic HTML response is not helpful. There is a standard for this type of details about an error: RFC-9457. And this library provides a simple way to map exceptions to this format.

== Spec & API

This has been proposed to and rejected by several existing specs:

* https://github.com/jakartaee/rest/issues/839[Jakarta REST (JAX-RS)]; a second discussion was also https://github.com/jakartaee/rest/issues/1150[rejected].

* https://github.com/eclipse/microprofile-rest-client/issues/248[MP REST Client].

The API in the `api` module looks quite stable. Some first ideas for a full spec follow below. It's yet far from complete, but it's a start:

* MUST `application/problem+json`, `application/problem+xml`; SHOULD any, e.g. `+yaml`

* SHOULD render `text/html`

* map also `@Valid` REST params

* logging: 4xx = DEBUG, 5xx = ERROR; configurable?

* order of extensions is alphabetic (which is better for tests than random)

* multiple extensions with the same name: undefined behavior

* JAXB can't unmarshal a subclass with the same type and namespace

* Security considerations: nothing dangerous in problem details (i.e. exception message); stack-trace in logs

* TODO scan client classpath for @Type annotated exceptions (and document this in the spec and the annotation)

* TODO inherited annotations

* TODO cause annotations

* TODO type factory, e.g. URL to OpenAPI

* TODO instance factory, e.g. URL to the logging system filtering on an UUID

== Dummy-Impl [ri]

It's called `ri`, but it's actually only a POC, and it's incomplete. See the README for details.

== Test

The `test` module runs integration tests by using https://github.com/t1/jee-testcontainers[JEE Testcontainers], i.e. it can be configured to start different Docker containers with various JEE application servers. By default, it starts a Wildfly.

`testcontainer-running`

As the containers don't yet implement the API by themselves, the dummy implementation `ri` is hard-wired in the tests for now.

=== Wildfly

Default `mvn` or explicitly `mvn -Djee-testcontainer=wildfly`

=== Open Liberty

`mvn -Djee-testcontainer=open-liberty:19.0.0.9-javaee8-java11 -Pwith-slf4j`

needs tag for jdk11 support

needs dependencies on slf4j-api and slf4j-jdk14

=== TomEE

`mvn -Djee-testcontainer=tomee`

3 tests fail, because this version of TomEE (9.0.20 / 8.0.0-M3) doesn't write the problem detail response entity in some cases for some reason:

StandardExceptionMappingIT.shouldMapWebApplicationExceptionWithoutEntityButMessage

StandardExceptionMappingIT.shouldMapWebApplicationExceptionWithoutEntityOrMessage

ValidationFailedExceptionMappingIT.shouldMapValidationFailedException

=== Payara

`mvn -Djee-testcontainer=payara -Pwith-slf4j`

fails due to lack of jdk11 support of the https://hub.docker.com/r/payara/server-full[`payara`] image.

needs dependencies on slf4j-api and slf4j-jdk14

== Spring

We build for JDK 11 and the Jakarta EE 10 APIs. The current versions of Spring Boot don't support this combination. But you can still use the older `com.github.t1:problem-details-api:1.0.10`, which was based on Jakarta EE 8.