Why Adding Spring HATEOAS Stops Front‑End Teams From Chasing Swagger Updates

When building APIs, developers often struggle with exposing state transitions such as an order moving from [PENDING_REVIEW] to [REVIEWED], forcing front‑end code to hard‑code if‑else checks and constantly update Swagger documentation.

From CRUD to Hypermedia

Most APIs only achieve Richardson Level 2, returning plain data like:

{
  "code": 200,
  "msg": "success",
  "data": {
    "orderId": "8848",
    "status": "PENDING_REVIEW"
  }
}

Clients must infer the next possible actions. By adding Spring HATEOAS (Level 3), the response gains a self‑describing _links section:

{
  "code": 200,
  "msg": "success",
  "data": {
    "orderId": "8848",
    "status": "PENDING_REVIEW",
    "_links": {
      "self": {"href": "http://api.yann.com/orders/8848"},
      "cancel": {"href": "http://api.yann.com/orders/8848/cancel"}
    }
  }
}

The front‑end can now simply render a cancel button when the _links.cancel entry exists, eliminating manual status checks.

Practical Implementation

Include the starter dependency: spring-boot-starter-hateoas Example controller:

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

    @GetMapping("/{id}")
    public R<EntityModel<Order>> getOrder(@PathVariable Long id) {
        Order order = new Order(id, "MacBook Pro", "PENDING_REVIEW");
        EntityModel<Order> resource = EntityModel.of(order);
        resource.add(linkTo(methodOn(OrderController.class).getOrder(id)).withSelfRel();
        if ("PENDING_REVIEW".equals(order.getStatus())) {
            resource.add(linkTo(methodOn(OrderController.class).cancelOrder(id)).withRel("cancel"));
        }
        return R.ok(resource);
    }

    // ... cancelOrder method omitted
}

The linkTo(methodOn(...)) construct uses strong‑typed class and method references, so URL changes (e.g., /api/orders → /api/v2/orders) automatically propagate to generated links, providing compile‑time safety.

Combining HATEOAS with RBAC

To prevent exposing unauthorized actions, the link generation can be guarded by permission checks:

// Core logic: status check + RBAC
boolean hasCancelPerm = StpUtil.hasPermission("order:cancel");
if ("PENDING_REVIEW".equals(order.getStatus()) && hasCancelPerm) {
    resource.add(linkTo(methodOn(OrderController.class).cancelOrder(id)).withRel("cancel"));
}

Front‑end code becomes trivial:

<button v-if="_links.cancel" @click="doRequest(_links.cancel.href)">Cancel</button>

Thus the client no longer needs to know the permission code order:cancel or the exact URL; the back‑end enforces security and supplies only the links the caller is allowed to use.

Key Takeaways

Spring HATEOAS upgrades a plain JSON payload to a hypermedia‑rich response, reducing front‑end coupling.

Type‑safe link generation eliminates hard‑coded URLs and keeps them in sync with controller mappings.

Integrating with Spring Security or Sa‑Token enables fine‑grained permission checks directly in link assembly.

The approach mitigates both accidental exposure of internal endpoints and the constant need to update Swagger specifications.