Express.js Mastery / Express: Let’s Start Building The Natours API!

Starting Our API: Handling GET Requests

🌍 The Project: Natours

  • 🧳 A tour-booking application: view tours, book them, create accounts, log in, leave reviews, etc.

  • 🏗️ The course builds this in two phases:

    1. First: build the API (working with raw data only).

    2. Later: build the dynamically rendered website on top of it.

  • 🎯 Building the API first makes it easier to focus purely on learning Express, MongoDB, and Mongoose without also worrying about UI/design at the same time.

👀 Quick Look at the Final API (via Postman)

  • 🌐 Base endpoint: localhost:3000/api/v1

  • 📥 GET /api/v1/tours → returns all tours (matches the data seen on the rendered site).

  • 🔍 GET /api/v1/tours/:id → returns just that one tour, with much more detail (start locations, tour guides — which reference other IDs, locations, reviews, etc.).

  • There's also a users resource, but it requires authentication to access.

💡 This is just a preview — these advanced features get built up gradually through the course.

🛠️ Implementing: GET /api/v1/tours

🔹 Step 1: Remove/comment out the old test route

  • 💬 The earlier / GET/POST test routes are commented out (not deleted) since they're no longer needed.

🔹 Step 2: Set up the route with API versioning

app.get('/api/v1/tours', (req, res) => {
  // route handler
});

  • The callback function passed to .get() is called the route handler.

  • v1 in the URL = API versioning — good practice.

    • If breaking changes are needed later, a new v2 endpoint can be created without disrupting anyone still using v1.

    • Versioning could also be done via subdomain, but including it in the URL path is simpler.

🔹 Step 3: Read the tours data — outside the route handler, at top-level

  • Import the fs module

  • Core modules are conventionally required first, at the top of the file.

const fs = require('fs');

  • Data lives in dev-data/data/tours-simple.json — a JSON array of tour objects (similar structure to node-js course "node farm" project data).

  • Access JSON data in app.js

const tours = JSON.parse(
  fs.readFileSync(`${__dirname}/dev-data/data/tours-simple.json`)
);

📂 Reading the JSON File

  • ❓ Why read the file at the top of the file instead of inside the route handler?

    • 🚀 Top-level code runs only once when the server starts.

    • ⚡ This avoids reading the file on every incoming request.

    • ✅ Since it's outside the request handler, using readFileSync() is acceptable.

  • 📖 fs.readFileSync(path)

    • Reads the file synchronously and returns its contents.

  • 📁 __dirname

    • Refers to the absolute path of the current file's directory.

    • Helps build the correct file path regardless of where the app is run.

  • 🔄 JSON.parse()

    • Converts the JSON string into a JavaScript object or array.

🔹 Step 4: Send the data back using the JSend format

app.get('/api/v1/tours', (req, res) => {
  res.status(200).json({
    status: 'success',
    results: tours.length,
    data: {
      tours: tours,
    },
  });
});

  • ✅ res.status(200)

    • Sets the HTTP status code.

    • Although 200 is the default, explicitly setting it is considered good practice.

  • ✅ status

    • Indicates whether the request was successful.

    • Possible values:

      • 🟢 success → Successful request (2xx)

      • 🟡 fail → Client error (4xx)

      • 🔴 error → Server error (5xx)

  • 📂 data

    • Contains the actual response payload.

    • Typically named after the resource being returned (e.g., tours).

  • ⭐ results (Optional)

    • Shows the total number of items returned.

    • Useful when returning an array, but unnecessary for a single object.

    • Not part of the official JSend specification.

🔹 Step 6: Test in Postman

  • 🌐 URL: 127.0.0.1:3000/api/v1/tours

  • 📥 Method: GET

  • ✅ Result:

{
  "status": "success",
  "results": 9,
  "data": {
    "tours": [ ...9 tour objects... ]
  }
}

✅ Key Takeaway

  • 📄 This is currently a file-based API — data is read from a local JSON file, not a database (that comes later with MongoDB/Mongoose).

  • 📐 Pattern established:

    • 📖 Read data once, at the top level, outside any route handler.

    • 🛣️ Use app.get(url, callback) to define the route + handler.

    • 📦 Respond using res.status(code).json({ status, results, data: { resourceName } }) — the JSend-style envelope.

  • ➡️ Next step: implement the POST request to allow creating new tours.