HATEOAS Links and Rels — Designing Hypermedia Relationships

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

HATEOAS links consist of a target URL (href), a relationship type (rel) describing the link's meaning, and optionally the HTTP method required to follow it.

What You'll Learn

• Standard link relation types (self, next, prev, etc.)
• Custom rel values for domain-specific actions
• How to design consistent link structures

Why It Matters

Link relations are the vocabulary of your hypermedia API. Consistent, well-named rel values make your API intuitive and self-documenting.

flowchart LR
    A["Link Components"] --> B["href: URL"]
    A --> C["rel: Relationship"]
    A --> D["method: HTTP Verb"]
    A --> E["type: Media Type"]
    B --> F["https://api.example.com/users/123"]
    C --> G["self, next, edit, delete"]
    style A fill:#dbeafe,stroke:#2563eb

Code Examples

# Standard link relations
response = {
    "id": 123,
    "name": "Alice",
    "_links": {
        "self": {"href": "/users/123", "method": "GET"},
        "collection": {"href": "/users", "method": "GET"},
        "edit": {"href": "/users/123", "method": "PUT"},
        "delete": {"href": "/users/123", "method": "DELETE"},
        "orders": {"href": "/users/123/orders", "method": "GET"},
        "next": {"href": "/users?page=2", "method": "GET"}
    }
}

# Following a link by rel
def follow_link(resource, rel):
    if rel in resource.get("_links", {}):
        link = resource["_links"][rel]
        return requests.request(link["method"], f"https://api.example.com{link['href']}")
    return None

// Client using rel values
const user = await fetchUser(123);
const ordersLink = user._links.find(l => l.rel === 'orders');
if (ordersLink) {
  const orders = await fetch(ordersLink.href);
  console.log(orders);
}

Common Mistakes

1. Using Inconsistent Rel Names

Mix "edit" on one resource, "update" on another. Standardize.

2. Omitting the self Rel

Every resource should have a self link pointing to its own URI.

3. Forgetting the Method

Without the HTTP method, clients must guess whether to GET or POST.

4. Using Verbs as Rel Values

Use standard rel types (edit, delete) instead of verbs (updateUser).

5. Not Documenting Custom Rels

Standard rels like self and next are well-known. Document custom domain rels.

Practice Questions

1. What does rel stand for in a hypermedia link?
2. What is the purpose of the self link?
3. Name three standard IANA link relations.
4. How do custom rels differ from standard ones?
5. Why should links include the HTTP method?

Answers:

1. Relationship — describes how the linked resource relates to the current one.
2. It points to the canonical URI of the current resource.
3. self, next, prev, first, last, edit, delete.
4. Custom rels are namespaced (e.g., https://api.example.com/rels/pay).
5. So clients know whether to GET, POST, PUT, or DELETE.

Challenge: Design link relations for an e-commerce API covering products, carts, checkout, payments, and order tracking.

FAQ

What's Next

Explore Link Formats including HAL and JSON:API, then learn about Actions and Forms for state transitions.