Java library for working with RFC 9457 Problems

[pvdbosch]

Goal is to create an open-source library to work with RFC 9457 Problems that are compliant with the Belgif REST guide.

It could be based on CBSS' rest-problem library.

It was presented on WG of 2024-01-24:

• This library supports JAX-RS, MicroProfile REST client and Spring Boot integration.
• It maps each problem "type" to a specific Java exception class, allowing to work with Problems naturally within Java as exceptions that are thrown or catched.
• It provides support for the standardized Belgif problems, and is extensible to other custom types with a fallback for unknown problem types
• some CBSS-specific logic would need to be extracted from the library
• mapping is supported from Bean Validation exceptions to a belgif badRequestProblem

Feedback:

• interesting library, seems easy to use
• most participants are interested in Spring Boot case. Using the library within Spring Boot, requires also adding some JEE-specific API jar files (JAX-RS, CDI). Would be interesting if this dependency can be removed.
• the library contains a RequestValidator for standard OpenAPI types like EnterpriseNumber or Ssin (e.g. checksum validation). To discuss if this might be best extracted to another library (or multiple ones)

[pvdbosch]

next steps:

• CBSS: check if OK to open source
• @pvdbosch : verify further within Smals if (evolution of) this library fits requirements; and check with eHealth

[pvdbosch]

first feedback from within Smals is same as mentioned on WG (incl to separate validation logic from the problem lib) and positive about this initiative

[jpraet]

For the Spring Boot users:

• do you use @RestController and RestTemplate? (those are currently supported by the problem library)
• anyone using the org.springframework.web.reactive.client.WebClient? (currently not yet supported)
• anyone using the Spring Boot 3.2 RestClient already? (currently not yet supported)
• do you use Bean Validation in Spring Boot apps? (currently not yet supported as I extracted that to the *-java-ee module)

For the Java EE users:

• do you use MicroProfile REST Client? (this is currently supported by the problem library)
• do you use the JAX-RS 2.0 Client API? I did not manage to get it working to get this to transparently throw a Problem exception. I attempted to do that with a ClientResponseFilter. But if I throw a Problem exception in that filter, it gets wrapped in a ResponseProcessingException. So the client application cannot just catch Problem, but needs to unwrap the ResponseProcessingException first.

General question:

At CBSS, besides the configuration for the polymorhpic deserialization of the Problem types, we also apply following configuration to Jackson ObjectMapper:

• register com.fasterxml.jackson.datatype.jsr310.JavaTimeModule so we can work with LocalDate, OffsetDateTime, ...
• disable SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, so date types don't get serialized as numeric timestamps
• disable DeserializationFeature.ADJUST_DATES_TO_CONTEXT_TIME_ZONE, so the timezone of date types is left untouched during deserialization
• disable DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, to ignore unknown properties during deserialization evo-compat
• setSerializationInclusion(Include.NON_NULL), to not serialize null properties jsn-null

These are not really related to the problem library per se, but more for general compliance with the Belgif REST Guidelines. I'm not sure whether those customizations should be included in the problem library?

[pvdbosch]

For the Spring Boot users:

• do you use @RestController and RestTemplate? (those are currently supported by the problem library)

yes

• anyone using the org.springframework.web.reactive.client.WebClient? (currently not yet supported)

no

• anyone using the Spring Boot 3.2 RestClient already? (currently not yet supported)

no

• do you use Bean Validation in Spring Boot apps? (currently not yet supported as I extracted that to the *-java-ee module)

yes

For the Java EE users:

• do you use MicroProfile REST Client? (this is currently supported by the problem library) no (isn't activated yet in base image)

• do you use the JAX-RS 2.0 Client API? I did not manage to get it working to get this to transparently throw a Problem exception.

yes, generated by our own variant of the jaxrs-spec language of openapi-generator

General question:

we also apply following configuration to Jackson ObjectMapper: ... These are not really related to the problem library per se, but more for general compliance with the Belgif REST Guidelines. I'm not sure whether those customizations should be included in the problem library?

I don't think so, Smals has similarly a rest-jackson library with a variant of these customizations that does "mapper.findAndRegisterModules()"

[jpraet]

For the groupId and top-level java package: "io.github.belgif.problem"? And for the repo name: "belgif-problem"? or just "problem"?

[pvdbosch]

suggestions: groupId: io.github.belgif.rest.problem artifactId: belgif-rest-problem

GitHub repo name: rest-problem-java

Rationale:

• consistency with openapi artifacts: artifactId prefixed with "belgif", while repo isn't (github organization is already "belgif")
• repos for non-java support (e.g. javascript/typescript) might be added at some point
• use of maven artifact already implies "java"

[pvdbosch]

CBSS has worked on this lib:

• lib is now decoupled from JEE
• Spring Boot is missing some features like Bean Validation
• extracting some CBSS-specific code
• other cleanup in progress

I'll create a "rest-problem-java" github repo under belgif.

[jpraet]

Github repo: https://github.com/belgif/rest-problem-java Documentation: https://belgif.github.io/rest-problem-java/latest/ Javadoc: https://belgif.github.io/rest-problem-java/latest/apidocs/ Maven Central: https://central.sonatype.com/namespace/io.github.belgif.rest.problem

Initial pre-release version 0.1.0 is available. Feedback is welcome.