HATEOAS vs GraphQL — Contrasting Hypermedia and Query-Based APIs

In this tutorial, you will learn about HATEOAS vs Graphql. We cover key concepts, practical examples, and best practices to help you master this topic.

HATEOAS and GraphQL represent fundamentally different approaches: HATEOAS uses server-driven hypermedia navigation while GraphQL uses client-driven queries with runtime data selection.

What You'll Learn

• How HATEOAS and GraphQL differ in philosophy
• When to use each approach
• Can they be combined?

Why It Matters

Choosing between HATEOAS and GraphQL affects your API's coupling, discoverability, and flexibility. Understanding both helps you make the right architectural decision.

flowchart TD
    A["API Design Approaches"] --> B["HATEOAS"]
    A --> C["GraphQL"]
    B --> D["Server-driven navigation"]
    B --> E["Links guide client flow"]
    B --> F["Discoverable at runtime"]
    C --> G["Client-driven queries"]
    C --> H["Client selects fields"]
    C --> I["Strongly typed schema"]
    style A fill:#dbeafe,stroke:#2563eb

Comparison

Code Examples

# HATEOAS: server provides next steps
response = get("/orders/123")
# Client follows server-provided links
if "pay" in response["_actions"]:
    post(response["_actions"]["pay"]["href"], data)

# GraphQL: client requests what it needs
query = """
query {
  order(id: "123") {
    status
    total
    items { name price }
  }
}
"""
post("/graphql", json={"query": query})

Common Mistakes

1. Forcing HATEOAS When GraphQL Is Better

Complex UIs needing flexible data selection benefit more from GraphQL.

2. Using GraphQL Where HATEOAS Sufficed

Simple CRUD APIs don't need GraphQL's complexity.

3. Trying to Replace One with the Other

They solve different problems. HATEOAS handles navigation; GraphQL handles data fetching.

4. Ignoring Caching Tradeoffs

HATEOAS benefits from built-in HTTP caching; GraphQL requires manual cache configuration.

5. Mixing Both Without Clear Boundaries

If using both, clearly separate HATEOAS endpoints from GraphQL endpoints.

Practice Questions

1. Who controls navigation in HATEOAS vs GraphQL?
2. How does discoverability work in each approach?
3. Which approach has better caching characteristics?
4. When would you choose HATEOAS over GraphQL?
5. Can you use both in the same API?

Answers:

1. Server in HATEOAS; client in GraphQL.
2. HATEOAS at runtime via links; GraphQL at dev time via schema introspection.
3. HATEOAS benefits from built-in HTTP caching; GraphQL needs custom cache layers.
4. For public APIs, CRUD-heavy services, or when HTTP caching is important.
5. Yes. Use REST+HATEOAS for CRUD and GraphQL for complex dashboard queries.

Challenge: Design an e-commerce API that uses HATEOAS for order management (state transitions) and GraphQL for the product catalog (flexible queries).

FAQ

What's Next

Explore HATEOAS Design Patterns for implementation strategies, then review HATEOAS Examples in popular APIs.