diff --git a/README.md b/README.md index 27066b9..4d6d704 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/semantic-contract.md b/docs/semantic-contract.md index 5eb3786..831d064 100644 --- a/docs/semantic-contract.md +++ b/docs/semantic-contract.md @@ -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