Why API documentation matters in Express - See It in Action

Why API documentation matters

📖 Scenario: You are building a simple Express server that provides information about books. Good API documentation helps other developers understand how to use your server endpoints correctly.

🎯 Goal: Create a basic Express server with a single endpoint /books that returns a list of books. Add clear comments to document the API endpoint, explaining what it does and how to use it.

📋 What You'll Learn

Create an Express app with a /books GET endpoint

Define a list of books as an array of objects with id and title

Add a configuration variable for the port number

Add comments above the endpoint to document its purpose and usage

Start the server listening on the configured port

💡 Why This Matters

🌍 Real World

API documentation helps developers understand how to use your server endpoints without confusion, saving time and reducing mistakes.

💼 Career

Clear API documentation is a key skill for backend developers and anyone working with web services or APIs.

1

DATA SETUP: Create the books data array

Create a constant array called books with these exact objects: { id: 1, title: '1984' }, { id: 2, title: 'Brave New World' }, and { id: 3, title: 'Fahrenheit 451' }.

Express

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

Need a hint?

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

2

CONFIGURATION: Set the server port

Create a constant called PORT and set it to 3000.

Express

const books = [
  { id: 1, title: '1984' },
  { id: 2, title: 'Brave New World' },
  { id: 3, title: 'Fahrenheit 451' }
];

// Set the server port to 3000
// Your code here

Need a hint?

Use const PORT = 3000; to set the port.

3

CORE LOGIC: Create the Express app and the /books endpoint

Import Express, create an app with express(), and add a GET endpoint /books that sends the books array as JSON.

Express

const books = [
  { id: 1, title: '1984' },
  { id: 2, title: 'Brave New World' },
  { id: 3, title: 'Fahrenheit 451' }
];

const PORT = 3000;

// Import express and create app
// Add GET /books endpoint to send books as JSON
// Your code here

Need a hint?

Use const express = require('express'); and const app = express();. Then add app.get('/books', (req, res) => { res.json(books); });.

4

COMPLETION: Add API documentation comments and start the server

Add a comment above the /books endpoint explaining it returns a list of books as JSON. Then add app.listen(PORT) to start the server.

Express

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

const books = [
  { id: 1, title: '1984' },
  { id: 2, title: 'Brave New World' },
  { id: 3, title: 'Fahrenheit 451' }
];

const PORT = 3000;

// Add a comment describing the /books endpoint
// Start the server listening on PORT
// Your code here

Need a hint?

Add a comment like // GET /books endpoint returns a list of books as JSON above the endpoint. Then add app.listen(PORT); below.