Problem JSON (application/problem+json) in Spring WebFlux

In this article, we will explore what Problem JSON is, why it is used, and how to utilize the "Problem: Spring WebFlux" library to generate application/problem+json responses in a Spring WebFlux project.

You can find more information about the library and its usage here.

Why to use Problem JSON ?

Using application/problem+json responses with the "Problem Spring Web" library offers several advantages for building robust and standardized error handling in your Spring-based applications.

1) Adopting application/problem+json ensures that your API error responses follow a standardized format as defined by RFC 7807. This consistency makes it easier for clients to parse and handle errors.

2) The problem details provided in the JSON payload help clients understand what went wrong. Fields like type, title, status, detail, and instance offer comprehensive information about the error.

3) Clients can programmatically inspect and handle errors based on standardized fields, leading to better error management and user experience.

4) Standardized error responses improve interoperability between different services and clients, as the format is widely recognized and understood.

What is Problem JSON?

Problem JSON typically refers to a standardized format used for representing error details in JSON (JavaScript Object Notation) format. This format is often used in web APIs to provide clients with structured error messages that can be easily parsed and understood.

The format helps ensure consistency in how errors are communicated between services and clients.

One of the most common specifications for Problem JSON is the Problem Details for HTTP APIs (RFC 7807), which defines a standard way to express HTTP error responses. Here's a basic example of a Problem JSON according to RFC 7807:

Components of Problem JSON (RFC 7807)

Default Components

The default components of Problem JSON as specified in RFC 7807 are:

1) type (string): A URI reference that identifies the problem type. When dereferenced, it might provide human-readable documentation for the problem type.

2) title (string): A short, human-readable summary of the problem type. This should not change from occurrence to occurrence of the problem, except for localization purposes.

3) status (integer): The HTTP status code generated by the origin server for this occurrence of the problem.

4) detail (string): A human-readable explanation specific to this occurrence of the problem.

5) instance (string): A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

According to RFC 7807, the "type" field is the only mandatory property in a Problem JSON payload.

However, in practical use, it's common and beneficial to include additional fields to provide more context about the problem. The default components such as title, status, detail, and instance are typically included to give a fuller picture of the error, even though they are not strictly required.

Here's an expanded example for clarity:

Custom Components

RFC 7807 allows for the inclusion of additional, custom properties to extend the problem details with more specific information relevant to the application. These properties are included alongside the default components.Here are some example Custom Properties:

1) timestamp (string): Indicates when the error occurred.

2) errors (array): A list of specific error messages or codes.

3) traceId (string): An identifier for tracing the request through various systems.

4) additionalData (object): An object containing more detailed error information.

Example of Problem JSON with Custom Components

Here's an example of a Problem JSON response with custom components.

What is "application/problem+json" ?

To signal to the client that the payload is a "Problem" as per RFC 7807, the server should set the Content-Type HTTP header to application/problem+json. This header indicates that the response body is formatted as a Problem JSON.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

By setting the Content-Type header to application/problem+json, clients can programmatically recognize and handle Problem JSON responses appropriately.

How to use "Problem: Spring WebFlux" library

The Problem Spring Web Library simplifies the implementation of RFC 7807 in Spring applications. It handles the creation and formatting of application/problem+json responses, reducing boilerplate code and potential errors.

Add Dependencies

Ensure you have the required dependencies problem-spring-webflux and jackson-datatype-problem in your pom.xml. The final pom.xml would look like this:

Configuration

We need to add the following properties to the application.yml file:

Define Beans in a Configuration Class

Create a configuration class to define the ProblemModule and ConstraintViolationProblemModule beans:

Create Custom Exception Handler

Create a class that implements ProblemHandling and optionally overrides methods to customize error handling:

Create Custom Exception Class

Create a Java class that extends AbstractThrowableProblem to define your custom exception:

Throw Exceptions in Controllers

In your controllers, throw exceptions as needed. The Problem Spring WebFlux library will handle them and produce standardized problem responses.

In the UserController class below, exceptions intentionally thrown during request handling will be automatically converted into Problem objects.

If the userId is not found in USER_DB, a UserNotFoundProblem exception is thrown. The UserNotFoundProblem exception, which extends AbstractThrowableProblem, will be automatically converted into a Problem object.

The UnsupportedOperationException and AccessDeniedException will also be automatically converted into a Problem object.

Test

Since you have added springdoc-openapi-starter-webflux-ui to your pom.xml, you can use Swagger UI to test your application. Navigate to http://localhost:8080/webjars/swagger-ui/index.html (replace 8080 with your actual server port if different).

Source code: GitHub