Course contentsShow
← Software Engineering
Lesson 796 of 1,93324. REST API DesignFree lesson

Designing Hypermedia Responses

Structuring links, relations (rel), and affordances in JSON to make APIs discoverable and self-documenting.

Designing Hypermedia Responses

You'll learn how to structure links, relations, and affordances in JSON to make APIs discoverable and self-documenting.

The Core Idea

In the previous lesson, you learned about HATEOAS—the principle that APIs should tell clients what actions they can take next. Now we'll see how to actually structure those hypermedia responses in JSON.

Think of a hypermedia response like a choose-your-own-adventure book. Each page doesn't just give you the story—it tells you which pages you can turn to next and what happens if you do. Your API responses work the same way: they include not just data, but also links showing what the client can do with that data.

Key Components

Links

Each link points to a related resource or action. You include the URL (href) so clients don't need to construct URLs themselves.

Relations (rel)

The rel attribute describes what the link does—like "self" (the current resource), "next" (next page), or "delete" (remove this item). This makes links semantic and discoverable.

Affordances

Affordances communicate how to use a link: which HTTP method to use, what data format to send, or what fields are required. They answer "what can I do here and how?"

Example Structure

{
  "id": 42,
  "name": "Product X",
  "_links": {
    "self": { "href": "/products/42" },
    "update": { "href": "/products/42", "method": "PUT" },
    "delete": { "href": "/products/42", "method": "DELETE" },
    "orders": { "href": "/products/42/orders" }
  }
}

The client now knows it can update this product, delete it, or view its orders—without hardcoding those URLs.

Key Takeaway: Designing hypermedia responses means embedding links with clear relations and affordances, transforming your API into a self-documenting, navigable interface that guides clients through available actions.