hateoflux

hateoflux is a lightweight HATEOAS library specifically crafted for Spring WebFlux, designed to revolutionize the development of hypermedia-driven APIs in a reactive environment. By overcoming the limitations of existing solutions like Spring HATEOAS, hateoflux provides an easier, more intuitive, and maintainable approach to crafting HAL+JSON compliant APIs.

Key Benefits of hateoflux

• Clean Domain Models: Seperate your domain models from hypermedia concerns using resource wrappers.
• Minimized Boilerplate: Automatic link generation and simplified assemblers lead to cleaner code.
• Enhanced Pagination Support: Built-in pagination features streamline the handling of data collections with HalListWrapper.
• Focused Documentation: Offers detailed guides and examples tailored for reactive environments.

Core Features

• Resource Wrappers: Utilize HalResourceWrapper and HalListWrapper for encapsulating resources and collections effectively.
• Type-Safe Link Building: Easily manage hyperlinks in a type-safe manner.
• Pagination Support: Simplify pagination with automatic metadata and navigation links.
• Dynamic URL Templates: Easily define dynamic URLs using placeholders.
• Seamless Spring Integration: Compatibly integrates with existing Spring configurations and annotations.
• Assembler Interfaces: Reduce boilerplate code using FlatHalWrapperAssembler and EmbeddingHalWrapperAssembler.

Getting Started

To integrate hateoflux into your Spring WebFlux application, ensure you're using Java 17+, Gradle 8.5+, and Spring Boot 3.0.0 or higher. You can easily add it to your project as a dependency:

For Maven Users:

<dependency>
    <groupId>de.kamillionlabs</groupId>
    <artifactId>hateoflux</artifactId>
    <version>latest-version</version>
</dependency>

For Gradle Users:

dependencies {
    implementation 'de.kamillionlabs:hateoflux:latest-version'
}

Example Implementation

Here’s a quick example of creating a HalResourceWrapper to represent an OrderDTO:

@GetMapping("/order-no-embedded/{orderId}")
public Mono<HalResourceWrapper<OrderDTO, Void>> getOrder(@PathVariable int orderId) {
    Mono<OrderDTO> orderMono = orderService.getOrder(orderId);
    return orderMono.map(order -> HalResourceWrapper.wrap(order)
            .withLinks(
                    Link.of("orders/{orderId}/shipment")
                            .expand(orderId)
                            .withRel("shipment"),
                    Link.linkAsSelfOf("orders/" + orderId)
            ));
}

The resulting JSON will look like this:

{
   "id": 1234,
   "userId": 37,
   "total": 99.99,
   "status": "Processing",
   "_links": {
      "shipment": {
         "href": "orders/1234/shipment"
      },
      "self": {
         "href": "orders/1234"
      }
   }
}

Advanced Usage

Assemblers

Leverage assemblers to minimize boilerplate while managing wrapping and linking logic, allowing you to focus on your core business functionality:

@Component
public class OrderAssembler implements EmbeddingHalWrapperAssembler<OrderDTO, ShipmentDTO> {
    @Override
    public Class<OrderDTO> getResourceTClass() {
        return OrderDTO.class;
    }

    // Additional assembler methods...
}

Learn More

Explore additional practical examples in the hateoflux-demos repository and refer to the Cookbook: Examples & Use Cases for further insights.

Detailed Documentation

Comprehensive documentation can be accessed at hateoflux Documentation, which includes sections on:

• Core Concepts
• Link Building
• Assemblers
• Comparison with Spring HATEOAS

Conclusion

hateoflux streamlines the development process of hypermedia APIs in reactive applications, offering better maintainability and user experience. With its focus on clean architecture and developer-friendly features, hateoflux is an essential tool for modern Spring WebFlux applications.