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

Need a 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

Need a 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

Need a 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

Need a hint?

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