Kapitel 23 · Web

Spring HATEOAS und Hypermedia APIs

Typ: LibraryVersion 2 ausführlich

Spring HATEOAS hilft, REST-Repräsentationen mit Links, Resource Models und HAL/Hypermedia-Formaten zu erstellen.

Fachliche Einordnung

Hypermedia ist sinnvoll, wenn Clients nicht jeden Link hart kennen sollen oder wenn ein API fachliche Übergänge sichtbar machen soll.

Enterprise-Merksatz: Spring HATEOAS hilft, REST-Repräsentationen mit Links, Resource Models und HAL/Hypermedia-Formaten zu erstellen.

Technische Darstellung

Kernkonzepte

EntityModel, CollectionModel und RepresentationModel.
WebMvcLinkBuilder für Controller-Links.
Assembler als Übersetzung zwischen Domäne und API-Modell.
HAL als verbreitetes Format.
Links als erlaubte Zustandsübergänge.

Wann einsetzen?

Du baust API-Navigation für externe Clients.
Du willst fachliche Aktionen abhängig vom Status anbieten.
Du brauchst discoverable APIs statt starrer URL-Dokumentation.

Typische Fehler und Risiken

Links mechanisch überall hinzufügen ohne fachliche Bedeutung.
HATEOAS als Ersatz für gute Dokumentation sehen.
JPA Entities direkt in Resource Models packen.

Legacy- und Modernisierungssicht

Alte Portal-/SOAP-Aktionen können in REST-Resources mit expliziten Links für erlaubte Folgeschritte überführt werden.

Ausführliches Beispiel

Das Beispiel zeigt bewusst nicht nur Annotationen, sondern auch die Verantwortung der Schicht. In echten Projekten sollte der technische Spring-Code an Adapter- oder Konfigurationsrändern bleiben, während die Fachlogik testbar und möglichst frameworkarm bleibt.

class OrderModelAssembler implements RepresentationModelAssembler<OrderView, EntityModel<OrderView>> {
    @Override
    public EntityModel<OrderView> toModel(OrderView order) {
        EntityModel<OrderView> model = EntityModel.of(order,
            linkTo(methodOn(OrderController.class).find(order.id())).withSelfRel());
        if (order.status() == OrderStatus.DRAFT) {
            model.add(linkTo(methodOn(OrderController.class).submit(order.id())).withRel("submit"));
        }
        return model;
    }
}

Checkliste für Reviews

Ist die Verantwortung des Bausteins klar: Framework steuert Lebenszyklus, Library wird gezielt benutzt?
Ist die Fachlogik außerhalb von Controller, Listener, Repository-Implementierung oder Konfiguration?
Sind Fehlerfälle, Timeouts, Security, Monitoring und Tests sichtbar modelliert?
Gibt es klare Grenzen zwischen DTO, Domäne, Persistence und Infrastruktur?