On paper it’s “more RESTful.” In production, it’s “maybe later.”

Why Spring HATEOAS Never Left the Developer Laptop

A practical take on hypermedia dreams, real-world constraints, and why most teams quietly moved on.

Photo by orbtal media on Unsplash

Spring HATEOAS is Spring’s implementation of HATEOAS: instead of just returning JSON data, your API also returns hypermedia links that tell the client what it can do next — like “self”, “update”, “delete”, “next page”, and so on. In theory, clients never need hardcoded URLs; they just follow links. Discoverability, evolvability, and a neat Level 3 Richardson Maturity Model badge

In reality, most teams I’ve worked with (and many I observe) never took it beyond the dev laptop. They tried it on one resource, demoed the cool _links section in Postman… and quietly stopped there.

What Spring HATEOAS Promises

On the whiteboard, Spring HATEOAS solves a few real problems.

• Discoverable APIs. Clients can navigate workflows by following links instead of memorizing endpoints.
• Looser coupling. Backend teams can refactor URLs or split services without breaking clients — as long as link relations stay stable
• Self-documenting responses. A new consumer can hit one endpoint and “see” what’s possible via links, almost like inline documentation
• Better UI behavior. Frontends can enable or disable buttons based on whether corresponding action links exist in the payload

These are not imaginary benefits. In complex domains, especially where flows are long, dynamic, or permission-driven, HATEOAS can genuinely simplify client logic and keep UI “dumb but correct.”

Why It Stayed in Dev Environments

So with all these benefits, why didn’t Spring HATEOAS become the default way we build APIs?

1. Complexity Tax for “Non-Business” Work

Every link you add is extra code that doesn’t directly ship a feature: link building, relation naming, conditional links, and keeping them in sync with business rules. Teams already struggle to keep DTOs, mappers, and validations clean. Adding hypermedia on top feels like yet another layer of ceremony.

In a backlog review, “add HATEOAS links to all resources” loses every time to “new feature X for customer Y.”

2. Payload Bloat and Performance Anxiety

HATEOAS inflates response sizes, sometimes significantly in list endpoints or deep aggregates. In high-throughput systems — or anything already fighting for every millisecond and kilobyte — engineers are reluctant to add metadata that most consumers might ignore anyway.

Once someone in the team says, “Do we really want to add 30% to our response size for links no one uses?” the conversation usually ends.

3. Weak Client and Tooling Support

Most HTTP clients, API gateways, and documentation tools don’t truly “speak HATEOAS.”

• OpenAPI/Swagger is path-centric, not link-centric.
• Frontend frameworks don’t natively parse and reason about _links.
• Mobile and native apps often prefer fixed contracts and typed clients.

So you end up with the worst of both worlds: effort to generate links on the server, and clients that still hardcode URLs or only partially consume them

4. Learning Curve and Cognitive Overhead

HATEOAS is not just “add some links.” It’s a design mindset: choosing stable relation names, thinking in terms of state transitions, and modeling workflows as graph navigation.taronko

For teams already juggling DDD, CQRS, hexagonal architecture, and microservices, “plus hypermedia semantics” often feels like one abstraction too many.

5. “Good Enough” Static APIs

Most internal APIs are consumed by 2–3 known clients, often within the same company. Those teams talk on Slack, share Swagger, and release in lockstep. For them, a well-documented, versioned, static REST API is “good enough.”

When static URLs already work and coordination cost is low, HATEOAS looks like over-engineering.

Pros and Cons in Practice

Here’s how it looks when you actually ship something with Spring HATEOAS.

Where It Helps

• Evolving flows without breaking clients. You can add, remove, or reorder steps in a workflow by changing which links are emitted, without shipping new frontend code every time
• Permission-driven UIs. When links are generated based on roles and state, buttons appear/disappear automatically as permissions change
• Onboarding new consumers. For external/public APIs, self-describing responses can be a gentle, guided path into your domain

What Hurts Day-to-Day

• Extra implementation work. Link assemblers, custom models, and conditional logic — all of it adds non-trivial complexity on the server
• Bigger responses. More bytes over the wire, more JSON to parse, more logs to sift through
• Partial or zero usage. Many clients ignore the hypermedia and treat the API like a plain JSON service, making your investment feel wasted

Challenges in Productionizing Spring HATEOAS

Getting a demo working is easy. Getting it into production and keeping it healthy is where most teams fall off.

1. Cross-team buy-in. HATEOAS only shines when both sides agree to design for it: backend commits to stable link semantics, frontend commits to consuming them. Without that handshake, it becomes busywork
2. Testing and contracts. You now test not just the payload shape, but also the presence, absence, and correctness of links under different states and roles. That’s more contract tests, more fixtures, more maintenance
3. Documentation mismatch. Standard API docs show paths and schemas, but not “if you’re in state A, you’ll see links X and Y.” You either document that separately or accept that your hypermedia story is invisible in Swagger
4. Performance and observability. Dynamic link generation can add CPU overhead and make payload inspection noisy. Teams already under pressure to reduce latency and log volume rarely want to add more moving parts
5. Versioning and evolution. Even with links, you still face versioning decisions: media types, link relation changes, semantic shifts. Mismanaging this can make things more confusing than a plain /v1 path strategy.

So Why Didn’t It Take Off?

Not because Spring HATEOAS is “bad” — the library is stable, actively maintained, and integrates nicely with Spring Boot. It’s more that the industry collectively answered a quiet question:docs

“Are the benefits of hypermedia worth the extra complexity, for our kind of APIs and teams?”

For a few sophisticated, heavily integrated systems, the answer is yes, and they run Spring HATEOAS successfully in production. For the majority of CRUD-ish, internal, or tightly coordinated services, the answer is still no

Teams quietly chose simpler alternatives instead:

• OpenAPI + Problem Details: Static contracts via Swagger + standardized error payloads (application/problem+json). Clients get discoverability through docs, not links​
• JSON:API: Structured hypermedia lite — pagination, relationships, sparse fieldsets. Less ceremony than full HATEOAS, better tooling (Postman, Apollo).​
• GraphQL: Single endpoint, schema introspection, field-level authorization. Solves 80% of HATEOAS discoverability without link parsing​
• gRPC + Protobuf: Strongly typed contracts, streaming, bidirectional RPC. For internal services where evolvability < performance​

The pattern? When static REST works fine (and tooling loves it), add standards incrementally — not a full hypermedia paradigm shift. Spring HATEOAS ends up as that interesting library many of us try on a Friday afternoon, demo in Postman, and then leave on the branch called spike/hateoas-poc.

Where in your current stack do you feel HATEOAS would genuinely simplify life rather than add one more abstraction to babysit?

About the author Sriram is a platform and backend engineer with 25+ years of experience building large-scale systems, cloud platforms, and developer enablement tooling. He writes about real-world engineering lessons, architecture trade-offs, and the “why” behind systems.

If this resonated, feel free to follow for more reflections on software engineering, architecture, and learning in public.