Documenting endpoints in Express - Mini Project: Build & Apply

Documenting Endpoints in Express

📖 Scenario: You are building a simple Express server that provides information about books. To help other developers understand your API, you will add documentation comments to your endpoints.

🎯 Goal: Create an Express server with one endpoint /books that returns a list of books. Add clear documentation comments above the endpoint describing its purpose, method, and response.

📋 What You'll Learn

Create an Express app with a /books GET endpoint

The endpoint should return a JSON array of book objects with title and author

Add a documentation comment above the endpoint explaining what it does

Include HTTP method and response details in the comment

💡 Why This Matters

🌍 Real World

Documenting API endpoints helps other developers understand how to use your server and what data to expect.

💼 Career

Clear API documentation is a key skill for backend developers and improves team collaboration and API usability.

1

Set up Express app and book data

Create a variable called books that is an array with these exact objects: { title: '1984', author: 'George Orwell' } and { title: 'To Kill a Mockingbird', author: 'Harper Lee' }. Then create an Express app by calling express() and assign it to a variable called app.

Express

# Create the books array and the Express app
# Your code here

Hint

Use const books = [...] to create the array. Use const app = express() to create the app.

2

Add a port configuration variable

Create a constant called PORT and set it to 3000. This will be the port your Express app listens on.

Express

const express = require('express');

const books = [
  { title: '1984', author: 'George Orwell' },
  { title: 'To Kill a Mockingbird', author: 'Harper Lee' }
];

const app = express();

# Create a constant PORT and set it to 3000
# Your code here

Hint

Use const PORT = 3000; to set the port number.

3

Add the /books GET endpoint with documentation comment

Add a GET endpoint on app for the path '/books'. Above it, write a documentation comment that explains: this endpoint returns a list of books, it uses the GET method, and it responds with JSON containing the books array. Inside the endpoint callback, send the books array as JSON.

Express

const express = require('express');

const books = [
  { title: '1984', author: 'George Orwell' },
  { title: 'To Kill a Mockingbird', author: 'Harper Lee' }
];

const app = express();

const PORT = 3000;

# Add a GET endpoint for '/books' with a documentation comment above it
# Your code here

Hint

Use app.get('/books', (req, res) => { ... }) and res.json(books). Add a comment starting with /** above the endpoint.

4

Start the server listening on the port

Add code to make the app listen on the PORT variable. Use app.listen(PORT).

Express

const express = require('express');

const books = [
  { title: '1984', author: 'George Orwell' },
  { title: 'To Kill a Mockingbird', author: 'Harper Lee' }
];

const app = express();

const PORT = 3000;

/**
 * GET /books
 * Returns a list of books as JSON.
 * Response: Array of book objects with title and author.
 */
app.get('/books', (req, res) => {
  res.json(books);
});

# Start the server listening on PORT
# Your code here

Hint

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

Practice

1. Why is it important to document endpoints in an Express app?

easy

A. To help others understand what each route does and how to use it

B. To make the app run faster

C. To reduce the size of the code

D. To hide the routes from users

Solution

1. Step 1: Understand the purpose of documentation

   Documentation explains the purpose and usage of code parts, making it easier for others to understand.

2. Step 2: Relate documentation to endpoints

   Documenting endpoints clarifies what each route does and what data it expects, helping teammates and future you.

3. Final Answer:

   To help others understand what each route does and how to use it -> Option A

4. Quick Check:

   Documentation improves understanding = B [OK]

Hint: Documentation explains purpose and usage clearly [OK]

Common Mistakes:

• Thinking documentation improves speed
• Confusing documentation with code optimization
• Assuming documentation hides code

2. Which of the following is the correct way to add a comment documenting an Express route?

easy

A. # This route handles user login

B. // This route handles user login

C.

D. /* This route handles user login */

Solution

1. Step 1: Identify comment syntax in JavaScript

   JavaScript uses // for single-line comments and /* */ for multi-line comments.

2. Step 2: Match comment style to Express (Node.js) code

   Express routes are written in JavaScript, so // is correct for single-line comments.

3. Final Answer:

   // This route handles user login -> Option B

4. Quick Check:

   JavaScript single-line comment = // [OK]

Hint: Use // for single-line comments in Express (JavaScript) [OK]

Common Mistakes:

• Using HTML comments in JS code
• Using # which is for Python or shell scripts
• Confusing multi-line comment style for single-line

3. Given this Express route with documentation:

  // Returns user info by ID
  app.get('/user/:id', (req, res) => {
    const id = req.params.id;
    res.send(`User ID is ${id}`);
  });

What will the server respond with when a client requests /user/42?

medium

A. Error: Route not found

B. User ID is :id

C. User ID is 42

D. User ID is undefined

Solution

1. Step 1: Understand route parameter usage

   The route uses :id as a parameter, which is accessed via req.params.id.

2. Step 2: Substitute parameter value from URL

   When requesting /user/42, req.params.id is '42', so the response is 'User ID is 42'.

3. Final Answer:

   User ID is 42 -> Option C

4. Quick Check:

   Route param :id = 42 in response [OK]

Hint: Route params accessed via req.params.name [OK]

Common Mistakes:

• Using literal ':id' instead of param value
• Accessing req.body instead of req.params
• Expecting undefined if param missing

4. This Express route has a documentation comment:

  // Get all products
  app.get('/products', (req, res) => {
    res.send(productsList);
  });

But when running, it throws an error: ReferenceError: productsList is not defined. What is the likely fix?

medium

A. Define the variable productsList before using it in the route

B. Change app.get to app.post

C. Remove the comment to fix the error

D. Rename the route path to /product-list

Solution

1. Step 1: Analyze the error message

   The error says productsList is not defined, meaning the variable is missing or not declared.

2. Step 2: Fix by declaring the variable

   To fix, declare and assign productsList before the route uses it, so the route can send it properly.

3. Final Answer:

   Define the variable productsList before using it in the route -> Option A

4. Quick Check:

   ReferenceError means missing variable = define it [OK]

Hint: Check error message for missing variables [OK]

Common Mistakes:

• Changing HTTP method without reason
• Thinking comments cause runtime errors
• Changing route path unrelated to variable error

5. You want to document an Express POST endpoint that creates a new user. Which of these comments best explains the endpoint clearly and helps future developers?

hard

A. // POST endpoint

B. // This is a route

C. // Handle user data

D. // POST /users - Creates a new user. Expects JSON body with 'name' and 'email'. Returns the created user object.

Solution

1. Step 1: Identify clear and complete documentation

   The best comment explains the HTTP method, route path, expected input, and output clearly.

2. Step 2: Compare options for clarity

   // POST /users - Creates a new user. Expects JSON body with 'name' and 'email'. Returns the created user object. describes method (POST), path (/users), expected data (JSON with 'name' and 'email'), and response (created user object), making it most helpful.

3. Final Answer:

   // POST /users - Creates a new user. Expects JSON body with 'name' and 'email'. Returns the created user object. -> Option D

4. Quick Check:

   Complete, clear docs = // POST /users - Creates a new user. Expects JSON body with 'name' and 'email'. Returns the created user object. [OK]

Hint: Include method, path, input, and output in comments [OK]

Common Mistakes:

• Writing vague or incomplete comments
• Not mentioning expected data format
• Ignoring response details