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

APIs and RESTful API Design

📖 What Is an API?

  • 🔌 API = Application Programming Interface.

  • 💬 On a high level: a piece of software that another piece of software can use, allowing applications to talk to each other.

  • 🌍 A web API: the server app sends data to a client whenever a request comes in — two pieces of software (client + server) communicating. This is the kind of API this course builds, and the most common type overall.

💡 APIs Are a Broader Concept (Not Just Web APIs)

"API" applies to any relatively standalone piece of software:

  • 📁 Node's fs/http modules — using readFile = using the FS API (hence "Node APIs").

  • 🌐 DOM manipulation — uses the browser's DOM API, not JavaScript itself.

  • 🏗️ A class's public methods — those methods are its API, letting other code interact with it.

🎯 For this course, the relevant meaning is specifically web APIs.

🏛️ REST Architecture

  • 🔤 REST = Representational State Transfer.

  • 🧩 A logical way of building web APIs that makes them easy to consume.

  • ✅ APIs that follow REST = RESTful APIs.

⭐ The Core REST Principles

  1. 📦 Separate the API into logical resources.

  2. 🛣️ Expose resources using structured, resource-based URLs (endpoints).

  3. 🔄 Use the correct HTTP methods (not the URL) to perform actions on data.

  4. 📄 Send/receive data using the JSON format.

  5. 🚫 APIs must be stateless.

📦 Principle 1 & 2: Resources and Endpoints

  • 📦 A resource = an object/representation of something with associated data (e.g. tours, users, reviews in the Natours example).

  • 🏷️ Any nameable piece of information can be a resource — must be a noun, not a verb.

  • 🌐 Resources are exposed via structured URLs. Example:

<https://www.natours.com/addNewTour>

This whole address is the URL; /addNewTour is the API endpoint.

❌ The Problem With Verb-Based Endpoints

Bad practice: /getTour, /addNewTour, /deleteTour — these mix actions (verbs) into the URL. This becomes a nightmare to maintain.

✅ The REST Fix: Use HTTP Methods, Not Verbs in URLs

  • /getTour → should just be /tours, accessed with a GET request.

  • Resource names in the URL should be plural (/tours, not /tour).

  • Calling /tours with GET → returns all tours.

  • To get a single tour (e.g. ID 7): /tours/7 (via URL segment or a unique identifier).

🔄 Principle 3: HTTP Methods Map to CRUD Operations

CRUD = Create, Read, Update, Delete — the four basic data operations.

🌐 HTTP Method

📝 CRUD Action

💡 Notes

GET

📖 Read

Retrieve data (e.g. all tours or one tour)

POST

➕ Create

Send data to create a new resource; ID is usually auto-generated by the server (not sent by client)

PUT

✏️ Update

Client sends the entire updated object

PATCH

🩹 Update

Client sends only the changed parts of the object

DELETE

🗑️ Delete

Deletes the resource identified by ID/unique identifier in the URL; usually requires authentication

💡 Key insight: The endpoint name stays the same (/tours) — only the HTTP method changes to indicate the action. GET on /tours reads data; POST on /tours creates data.

⚙️ Non-CRUD Actions

Some actions don't map to CRUD or a specific resource (e.g. login, search) — for these, get creative with endpoint names:

/login
/search

🔗 Combining Multiple Resources in One Endpoint

Example translations:

  • 👤 /getToursByUser → /users/3/tours (get all tours booked by user 3)

  • 🗑️ Delete tour 9 belonging to user 3 → similar nested endpoint with a DELETE request

💡 Only implement the resource combinations that actually make sense for your app/client — no need to build every possible combination.

📄 Principle 4: JSON Data Format

  • 📦 JSON = lightweight data-interchange format, used across virtually all web APIs (not JavaScript-specific).

  • 👍 Popular because it's easy for both humans and computers to read/write.

  • 📋 Similar to a JS object (key-value pairs), but:

    • 📝 All keys must be strings.

    • 🔢 Values are typically strings, but can also be numbers, booleans, other objects, or arrays.

📬 Response Formatting — JSON Standard

Raw data usually gets wrapped before sending, using a formatting standard. This course uses a simple one called JSend:

{
  "status": "success",
  "data": {
    "id": 5,
    "name": "The Sea Explorer"
  }
}

  • ✅ status — informs the client: success, fail, or error.

  • 📦 data — contains the actual requested data.

  • 📨 Wrapping data inside an extra object like this is called enveloping — a common practice that helps mitigate certain security issues.

  • 📚 Other formatting standards exist too (e.g. JSON:API, OData JSON Protocol).

🚫 Principle 5: Statelessness

  • In a stateless RESTful API, all state is handled on the client, never the server.

  • State = any piece of data in the app that can change over time (e.g. whether a user is logged in, which page you're currently on).

💡 Meaning: every request must contain all the information needed to process it — the server should never have to "remember" a previous request.

📖 Example — Pagination

❌ Bad (stateful) approach:

/tours/nextPage

This forces the server to remember what "current page" the client was on — the server has to track state. This is what REST avoids.

✅ Good (stateless) approach:

/tours/page/6

The client already knows it was on page 5 and requests page 6 directly. The server doesn't need to remember anything — it just returns page 6 as asked.

✅ Key Takeaway

  • REST = a structured, logical way to build web APIs.

  • 5 core principles: resources, structured URLs (endpoints), correct HTTP methods for actions, JSON format, and statelessness.

  • HTTP methods map to CRUD: GET = Read, POST = Create, PUT/PATCH = Update, DELETE = Delete.

  • Endpoint names should describe resources (nouns, plural), never actions (verbs) — the HTTP method conveys the action.

  • Responses are typically formatted (e.g. via JSend) and enveloped in a wrapper object with a status field.

  • Statelessness means every request is self-contained — the server holds no memory of past requests.