HATEOAS concept overview in Express - Mini Project: Build & Apply

HATEOAS Concept Overview with Express

📖 Scenario: You are building a simple Express server that provides information about books. You want to show how to include links in the API responses to guide clients on what actions they can take next. This is called HATEOAS, which helps clients discover API features dynamically.

🎯 Goal: Create an Express server that returns a list of books with HATEOAS links for each book. The links will show how to get details of a book and how to update it.

📋 What You'll Learn

Create an array called books with three book objects, each having id and title properties.

Create a variable called baseUrl set to "http://localhost:3000/books".

Create an Express GET route /books that returns the books array with HATEOAS links for each book.

Add a final line to start the Express server listening on port 3000.

💡 Why This Matters

🌍 Real World

APIs that guide clients with links help apps discover what actions are possible without guessing URLs. This makes APIs easier to use and evolve.

💼 Career

Understanding HATEOAS is useful for backend developers building RESTful APIs that are user-friendly and follow modern best practices.

1

DATA SETUP: Create the books array

Create an array called books with these exact objects: { id: 1, title: "The Hobbit" }, { id: 2, title: "1984" }, and { id: 3, title: "Pride and Prejudice" }.

Express

const express = require('express');
const app = express();

// Create the books array with 3 book objects
// Your code here

Hint

Use const books = [ ... ] with three objects inside.

2

CONFIGURATION: Define the base URL

Create a variable called baseUrl and set it to the string "http://localhost:3000/books".

Express

const express = require('express');
const app = express();

const books = [
  { id: 1, title: "The Hobbit" },
  { id: 2, title: "1984" },
  { id: 3, title: "Pride and Prejudice" }
];

// Define the baseUrl string
// Your code here

Hint

Use const baseUrl = "http://localhost:3000/books";

3

CORE LOGIC: Create the GET /books route with HATEOAS links

Create an Express GET route at /books that sends a JSON response. The response should be the books array where each book object includes a links array. Each links array must have two objects: one with rel: "self" and href set to the book's detail URL using baseUrl and the book's id, and another with rel: "update" and href set to the book's update URL similarly.

Express

const express = require('express');
const app = express();

const books = [
  { id: 1, title: "The Hobbit" },
  { id: 2, title: "1984" },
  { id: 3, title: "Pride and Prejudice" }
];

const baseUrl = "http://localhost:3000/books";

// Create GET /books route with HATEOAS links
// Your code here

Hint

Use app.get('/books', (req, res) => { ... }) and inside map each book to add a links array with the two link objects.

4

COMPLETION: Start the Express server on port 3000

Add a line to start the Express server listening on port 3000 using app.listen.

Express

const express = require('express');
const app = express();

const books = [
  { id: 1, title: "The Hobbit" },
  { id: 2, title: "1984" },
  { id: 3, title: "Pride and Prejudice" }
];

const baseUrl = "http://localhost:3000/books";

app.get('/books', (req, res) => {
  const booksWithLinks = books.map(book => ({
    ...book,
    links: [
      { rel: "self", href: `${baseUrl}/${book.id}` },
      { rel: "update", href: `${baseUrl}/${book.id}` }
    ]
  }));
  res.json(booksWithLinks);
});

// Start the server on port 3000
// Your code here

Hint

Use app.listen(3000); to start the server.

Practice

1. What is the main purpose of HATEOAS in an Express API?

easy

A. To encrypt API data for security

B. To speed up the server response time

C. To include links in responses that guide clients on possible next actions

D. To reduce the size of JSON responses

Solution

1. Step 1: Understand HATEOAS concept

   HATEOAS stands for Hypermedia As The Engine Of Application State, which means APIs provide links to guide clients on what to do next.

2. Step 2: Identify main purpose in Express API

   Express apps use HATEOAS by sending links in JSON responses to help clients discover available actions without extra docs.

3. Final Answer:

   To include links in responses that guide clients on possible next actions -> Option C

4. Quick Check:

   HATEOAS guides clients with links = C [OK]

Hint: HATEOAS means adding helpful links in API responses [OK]

Common Mistakes:

• Thinking HATEOAS speeds up server
• Confusing HATEOAS with encryption
• Believing it reduces JSON size

2. Which of the following is the correct way to include a HATEOAS link in an Express JSON response?

easy

A. res.json({ data: user, links: [{ rel: 'self', href: '/users/1' }] });

B. res.send('User');

C. res.json({ data: user, url: '/users/1' });

D. res.render('user', { link: '/users/1' });

Solution

1. Step 1: Identify JSON response with HATEOAS links

   HATEOAS links are included as part of JSON, usually in a 'links' array with 'rel' and 'href' keys.

2. Step 2: Check Express syntax for sending JSON

   res.json() sends JSON data; res.json({ data: user, links: [{ rel: 'self', href: '/users/1' }] }); correctly uses 'links' array with proper structure.

3. Final Answer:

   res.json({ data: user, links: [{ rel: 'self', href: '/users/1' }] }); -> Option A

4. Quick Check:

   HATEOAS links in JSON with rel/href = A [OK]

Hint: HATEOAS links go inside JSON under 'links' key [OK]

Common Mistakes:

• Sending HTML instead of JSON
• Using 'url' instead of 'links' array
• Rendering views instead of JSON

3. Given this Express route code, what will the JSON response include?

app.get('/books/:id', (req, res) => {
  const book = { id: req.params.id, title: 'Learn Express' };
  res.json({
    data: book,
    links: [
      { rel: 'self', href: `/books/${book.id}` },
      { rel: 'author', href: `/authors/123` }
    ]
  });
});

medium

A. Error because template literals are not allowed

B. Only book data without any links

C. HTML page showing book title

D. JSON with book data and two links: self and author

Solution

1. Step 1: Analyze the route handler

   The route sends JSON with 'data' containing book info and 'links' array with two link objects.

2. Step 2: Confirm template literals usage

   Template literals are valid in modern JavaScript, so href values will be correct URLs.

3. Final Answer:

   JSON with book data and two links: self and author -> Option D

4. Quick Check:

   Response includes data and links array = A [OK]

Hint: Look for 'links' array in JSON response to find HATEOAS links [OK]

Common Mistakes:

• Assuming no links are sent
• Confusing JSON with HTML output
• Thinking template literals cause errors

4. What is wrong with this Express code snippet trying to implement HATEOAS?

app.get('/items/:id', (req, res) => {
  const item = { id: req.params.id, name: 'Item A' };
  res.json({
    data: item,
    links: {
      rel: 'self',
      href: `/items/${item.id}`
    }
  });
});

medium

A. Missing status code in response

B. The 'links' property should be an array, not an object

C. res.json should be replaced with res.send

D. Template literals cannot be used inside JSON

Solution

1. Step 1: Check 'links' structure for HATEOAS

   HATEOAS expects 'links' to be an array of link objects, not a single object.

2. Step 2: Validate other code parts

   Template literals are valid, res.json is correct, and status code defaults to 200, so no issues there.

3. Final Answer:

   The 'links' property should be an array, not an object -> Option B

4. Quick Check:

   'links' must be array for multiple links = D [OK]

Hint: 'links' must be an array of objects, not a single object [OK]

Common Mistakes:

• Using object instead of array for 'links'
• Thinking template literals are invalid
• Replacing res.json with res.send unnecessarily

5. You want to design an Express API that uses HATEOAS to help clients navigate a blog. Which approach best applies HATEOAS principles?

hard

A. Include in each blog post response links to 'self', 'author', and 'comments' endpoints

B. Send only blog post data without any links to keep response small

C. Provide a separate documentation page listing all API URLs

D. Use query parameters to list all possible next URLs

Solution

1. Step 1: Recall HATEOAS goal

   HATEOAS guides clients by embedding links in responses to related resources or actions.

2. Step 2: Evaluate options for blog API

   Include in each blog post response links to 'self', 'author', and 'comments' endpoints includes links to related endpoints in each response, matching HATEOAS principles. Options A, C, and D do not embed navigational links in responses.

3. Final Answer:

   Include in each blog post response links to 'self', 'author', and 'comments' endpoints -> Option A

4. Quick Check:

   Embed navigational links in response = B [OK]

Hint: Embed related resource links inside each response for HATEOAS [OK]

Common Mistakes:

• Skipping links to keep response small
• Relying only on external docs
• Using query params instead of links