Spring HATEOAS — Hypermedia-Driven REST APIs

@Entity
public class Order {
    @Id @GeneratedValue
    private Long id;
    private String description;
    private BigDecimal total;

    @Enumerated(EnumType.STRING)
    private OrderStatus status; // PENDING, PAID, SHIPPED, CANCELLED

    @ManyToOne
    private Customer customer;

    // getters, setters, constructors
}

public enum OrderStatus {
    PENDING, PAID, SHIPPED, DELIVERED, CANCELLED
}

import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.*;

@Component
public class OrderModelAssembler implements RepresentationModelAssembler<Order, EntityModel<Order>> {

    @Override
    public EntityModel<Order> toModel(Order order) {
        EntityModel<Order> model = EntityModel.of(order);

        // Self link (always present)
        model.add(linkTo(methodOn(OrderController.class).getOrder(order.getId()))
            .withSelfRel());

        // Collection link
        model.add(linkTo(methodOn(OrderController.class).getAllOrders())
            .withRel("orders"));

        // Conditional links based on state
        if (order.getStatus() == OrderStatus.PENDING) {
            model.add(linkTo(methodOn(OrderController.class).cancelOrder(order.getId()))
                .withRel("cancel"));
            model.add(linkTo(methodOn(OrderController.class).payOrder(order.getId(), null))
                .withRel("pay"));
        }

        if (order.getStatus() == OrderStatus.PAID) {
            model.add(linkTo(methodOn(OrderController.class).shipOrder(order.getId()))
                .withRel("ship"));
        }

        // Related resource link
        if (order.getCustomer() != null) {
            model.add(linkTo(methodOn(CustomerController.class)
                .getCustomer(order.getCustomer().getId()))
                .withRel("customer"));
        }

        return model;
    }
}

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderService orderService;
    private final OrderModelAssembler assembler;
    private final PagedResourcesAssembler<Order> pagedAssembler;

    public OrderController(OrderService orderService,
                           OrderModelAssembler assembler,
                           PagedResourcesAssembler<Order> pagedAssembler) {
        this.orderService = orderService;
        this.assembler = assembler;
        this.pagedAssembler = pagedAssembler;
    }

    // GET /api/orders/{id}
    @GetMapping("/{id}")
    public EntityModel<Order> getOrder(@PathVariable Long id) {
        Order order = orderService.findById(id)
            .orElseThrow(() -> new OrderNotFoundException(id));
        return assembler.toModel(order);
    }

    // GET /api/orders
    @GetMapping
    public CollectionModel<EntityModel<Order>> getAllOrders() {
        List<EntityModel<Order>> orders = orderService.findAll().stream()
            .map(assembler::toModel)
            .toList();

        return CollectionModel.of(orders,
            linkTo(methodOn(OrderController.class).getAllOrders()).withSelfRel(),
            linkTo(methodOn(OrderController.class).createOrder(null)).withRel("create"));
    }

    // GET /api/orders/paged?page=0&size=20
    @GetMapping("/paged")
    public PagedModel<EntityModel<Order>> getOrdersPaged(Pageable pageable) {
        Page<Order> page = orderService.findAll(pageable);
        return pagedAssembler.toModel(page, assembler);
    }

    // POST /api/orders
    @PostMapping
    public ResponseEntity<EntityModel<Order>> createOrder(
            @RequestBody @Valid OrderRequest request) {
        Order order = orderService.create(request);
        EntityModel<Order> model = assembler.toModel(order);

        return ResponseEntity
            .created(model.getRequiredLink(IanaLinkRelations.SELF).toUri())
            .body(model);
    }

    // POST /api/orders/{id}/cancel
    @PostMapping("/{id}/cancel")
    public ResponseEntity<EntityModel<Order>> cancelOrder(@PathVariable Long id) {
        Order order = orderService.cancel(id);
        return ResponseEntity.ok(assembler.toModel(order));
    }

    // POST /api/orders/{id}/payment
    @PostMapping("/{id}/payment")
    public ResponseEntity<EntityModel<Order>> payOrder(
            @PathVariable Long id,
            @RequestBody PaymentRequest payment) {
        Order order = orderService.pay(id, payment);
        return ResponseEntity.ok(assembler.toModel(order));
    }

    // POST /api/orders/{id}/ship
    @PostMapping("/{id}/ship")
    public ResponseEntity<EntityModel<Order>> shipOrder(@PathVariable Long id) {
        Order order = orderService.ship(id);
        return ResponseEntity.ok(assembler.toModel(order));
    }
}

@GetMapping("/{id}")
public EntityModel<Order> getOrder(@PathVariable Long id) {
    Order order = orderService.findById(id).orElseThrow();

    Link selfLink = linkTo(methodOn(OrderController.class).getOrder(id))
        .withSelfRel()
        .andAffordance(afford(methodOn(OrderController.class).updateOrder(id, null)))
        .andAffordance(afford(methodOn(OrderController.class).cancelOrder(id)));

    return EntityModel.of(order, selfLink);
}

public class OrderSummaryModel extends RepresentationModel<OrderSummaryModel> {

    private final Long orderId;
    private final String status;
    private final BigDecimal total;
    private final String customerName;
    private final int itemCount;

    public OrderSummaryModel(Order order) {
        this.orderId = order.getId();
        this.status = order.getStatus().name();
        this.total = order.getTotal();
        this.customerName = order.getCustomer().getName();
        this.itemCount = order.getItems().size();
    }

    // getters...
}

// In controller
@GetMapping("/{id}/summary")
public OrderSummaryModel getOrderSummary(@PathVariable Long id) {
    Order order = orderService.findById(id).orElseThrow();
    OrderSummaryModel model = new OrderSummaryModel(order);

    model.add(linkTo(methodOn(OrderController.class).getOrder(id)).withRel("full"));
    model.add(linkTo(methodOn(OrderController.class).getOrderSummary(id)).withSelfRel());

    return model;
}

@WebMvcTest(OrderController.class)
class OrderControllerTest {

    @Autowired private MockMvc mockMvc;
    @MockBean private OrderService orderService;
    @Autowired private OrderModelAssembler assembler;

    @Test
    void shouldIncludeCancelLinkForPendingOrder() throws Exception {
        Order order = new Order(1L, "Test", BigDecimal.TEN, OrderStatus.PENDING);
        when(orderService.findById(1L)).thenReturn(Optional.of(order));

        mockMvc.perform(get("/api/orders/1").accept(MediaTypes.HAL_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.status").value("PENDING"))
            .andExpect(jsonPath("$._links.self.href").value(containsString("/orders/1")))
            .andExpect(jsonPath("$._links.cancel.href").value(containsString("/orders/1/cancel")))
            .andExpect(jsonPath("$._links.pay.href").exists());
    }

    @Test
    void shouldNotIncludeCancelLinkForShippedOrder() throws Exception {
        Order order = new Order(1L, "Test", BigDecimal.TEN, OrderStatus.SHIPPED);
        when(orderService.findById(1L)).thenReturn(Optional.of(order));

        mockMvc.perform(get("/api/orders/1").accept(MediaTypes.HAL_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$._links.cancel").doesNotExist())
            .andExpect(jsonPath("$._links.ship").doesNotExist());
    }
}