Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 25 additions & 99 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,128 +1,54 @@
# Codes

[![Maven Central](https://img.shields.io/maven-central/v/io.github.aalsanie/codes)](https://central.sonatype.com/artifact/io.github.aalsanie/codes)
[![CI](https://github.com/aalsanie/codes/actions/workflows/ci.yml/badge.svg)](https://github.com/aalsanie/codes/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Maven Central](https://img.shields.io/maven-central/v/io.github.aalsanie/codes)](https://central.sonatype.com/artifact/io.github.aalsanie/codes) [![CI](https://github.com/aalsanie/codes/actions/workflows/ci.yml/badge.svg)](https://github.com/aalsanie/codes/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

Codes is a lightweight Java library for reusable RFC 9457 problem type definitions with a dependency free core.

Spring provides `ProblemDetail` for an individual error occurrence. Codes provides the stable definition that can be reused across controllers, exception handlers, tests, and documentation.

```java
ProblemType ORDER_NOT_FOUND = ProblemType.of(
URI.create("https://api.example.com/problems/order-not-found"),
404,
"Order not found"
);
```

With Spring:

```java
ProblemDetail problem = ProblemDetails.forType(ORDER_NOT_FOUND);
```

or with occurrence-specific detail:

```java
ProblemDetail problem = ProblemDetails.forTypeAndDetail(
ORDER_NOT_FOUND,
"Order o-123 was not found."
);
```

The resulting problem keeps the reusable definition stable:

```json
{
"type": "https://api.example.com/problems/order-not-found",
"title": "Order not found",
"status": 404,
"detail": "Order o-123 was not found."
}
```
Define reusable [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) problem types in Java. Codes keeps the type, status, and title consistent across error responses, with a dependency-free core and an optional Spring adapter.

## Install

Java 17+. Add one of these to your Gradle `dependencies` block:

Core:

```kotlin
dependencies {
implementation("io.github.aalsanie:codes:0.4.0")
}
implementation("io.github.aalsanie:codes:0.4.0")
```

Spring:
Spring (also includes `codes`):

```kotlin
dependencies {
implementation("io.github.aalsanie:codes-spring:0.4.0")
}
implementation("io.github.aalsanie:codes-spring:0.4.0")
```

All artifacts require Java 17+.
Spring applications supply Spring Web; `codes-spring` does not include it transitively. [Core](https://central.sonatype.com/artifact/io.github.aalsanie/codes) · [Spring](https://central.sonatype.com/artifact/io.github.aalsanie/codes-spring) on Maven Central.

The core artifact has no runtime dependencies and publishes no Maven dependencies. `codes-spring` depends on the core artifact but does not impose a Spring Framework version; the application supplies Spring Web.
## Use

## Define a problem catalog

A problem type is an immutable value. Define reusable application problem types as constants:
Define a problem type once:

```java
final class OrderProblems {
static final ProblemType ORDER_NOT_FOUND = ProblemType.of(
URI.create("https://api.example.com/problems/order-not-found"),
404,
"Order not found"
);

static final ProblemType ORDER_ALREADY_CANCELLED = ProblemType.of(
URI.create("https://api.example.com/problems/order-already-cancelled"),
409,
"Order already cancelled"
);

private OrderProblems() {
}
}
static final ProblemType ORDER_NOT_FOUND = ProblemType.of(
URI.create("https://api.example.com/problems/order-not-found"),
404,
"Order not found"
);
```

Codes requires an absolute type URI, rejects `about:blank`, requires an HTTP status from 100 through 599, and requires a non-blank title. Use Spring's native `ProblemDetail.forStatus(...)` for status-only `about:blank` responses.

Different application exceptions can then reuse the same public problem type:
With Spring, create a new occurrence with its own detail:

```java
@ExceptionHandler(OrderNotFoundException.class)
ProblemDetail handleOrderNotFound(OrderNotFoundException ex) {
return ProblemDetails.forTypeAndDetail(
OrderProblems.ORDER_NOT_FOUND,
"Order " + ex.orderId() + " was not found."
);
}

@ExceptionHandler(ArchivedOrderNotFoundException.class)
ProblemDetail handleArchivedOrderNotFound(ArchivedOrderNotFoundException ex) {
return ProblemDetails.forTypeAndDetail(
OrderProblems.ORDER_NOT_FOUND,
"Archived order " + ex.orderId() + " was not found."
);
}
ProblemDetail problem = ProblemDetails.forTypeAndDetail(
ORDER_NOT_FOUND,
"Order o-123 was not found."
);
```

The library does not own exception handling, controller advice, localization, extension properties, or request-specific data. Those remain application and Spring concerns.

## When to use Codes

If an application only creates one or two `ProblemDetail` instances directly, a local helper may be simpler.

Codes is useful when problem types are part of the API contract and need to be defined once and reused consistently across multiple handlers, modules, tests, or documentation.
`ProblemDetails.forType(...)` creates an occurrence without a detail. Return the result from a Spring exception handler; Spring handles the HTTP response.

## Reference
Codes requires an absolute type URI other than `about:blank`, an HTTP status from 100 to 599, and a non-blank title. Exception handling and occurrence-specific data remain application concerns.

* [Spring integration](docs/integration-spring.md)
* [Semantic contract](docs/semantic-contract.md)
* [Compatibility policy](docs/compatibility-policy.md)
[Spring integration](docs/integration-spring.md) · [Problem type contract](docs/semantic-contract.md) · [Compatibility](docs/compatibility-policy.md) · [Contributing](CONTRIBUTING.md)

## License
[Apache-2.0](LICENSE).

Apache License 2.0.
**NOTE:** If an application only creates one or two `ProblemDetail` instances directly, a local helper may be simpler.
43 changes: 7 additions & 36 deletions docs/semantic-contract.md
Original file line number Diff line number Diff line change
@@ -1,49 +1,20 @@
# Semantic contract

Codes models reusable RFC 9457 problem type definitions.
A `ProblemType` is a reusable [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) problem type definition containing:

A `ProblemType` contains:

* an absolute type URI;
* an HTTP status between 100 and 599;
* an absolute type URI other than `about:blank`;
* an HTTP status from 100 to 599;
* a non-blank human-readable title.

`about:blank` is not a Codes problem type. It represents a status-only problem with no additional semantics beyond the HTTP status and is handled directly by HTTP frameworks such as Spring.

The type URI is the stable machine-readable identity of the problem type.

```java
ProblemType ORDER_NOT_FOUND = ProblemType.of(
URI.create("https://api.example.com/problems/order-not-found"),
404,
"Order not found"
);
```
These are Codes validation rules. RFC 9457 also permits relative type URI references, but Codes requires absolute URIs. `about:blank` represents a status-only problem with no additional semantics; use the HTTP framework's native support for it (for example, Spring's `ProblemDetail.forStatus(...)`).

## Definition and occurrence

`ProblemType` represents stable definition metadata.

It does not contain occurrence-specific information such as:

* detail;
* instance;
* request data;
* exception data;
* trace information;
* extension properties.

Those values belong to the individual RFC 9457 problem occurrence.

For Spring applications, `codes-spring` copies the stable definition into a native Spring `ProblemDetail`. Spring and the application remain responsible for the rest of the response lifecycle.

## Identity

Changing a problem type URI changes the public machine identity of the problem.
The type URI is the stable machine-readable identity of the problem. The title summarizes the type and normally remains stable across occurrences, except for localization.

Changing the Java exception or controller path that produces the problem does not require changing the problem type URI.
`ProblemType` holds only definition metadata. The `detail`, `instance`, request or exception information, traces, and extension properties belong to each occurrence. For Spring, `codes-spring` copies the definition into a new `ProblemDetail`; the application and Spring own the rest of the response lifecycle.

The title is a stable human-readable summary. Applications may localize it at the occurrence layer when required.
Changing a type URI changes the public problem identity. Changing the Java exception or controller that produces it does not require a new URI.

## Scope

Expand Down
Loading