Designing RESTful Endpoints and Routing

🌍 Introduction

When designing a RESTful API, it's important to follow best practices for naming routes, organizing endpoints, and handling different request types. In this lesson, you'll learn:

• How to structure RESTful endpoints.
• The best naming conventions for APIs.
• When to use query parameters vs. request body.
• How to organize routes effectively.

---

📌 1. Understanding RESTful API Endpoints

A RESTful API endpoint represents a resource (e.g., users, products, orders).
Each resource is accessed through a specific URL path.

✅ Example of a Well-Designed API

Action	HTTP Method	Endpoint
Get all users	GET	/users
Get a specific user	GET	/users/{id}
Create a new user	POST	/users
Update a user	PUT	/users/{id}
Partially update a user	PATCH	/users/{id}
Delete a user	DELETE	/users/{id}

---

📌 2. RESTful Naming Conventions

❌ Bad Examples

🚫 /getUsers → Use GET /users instead.
🚫 /deleteUser/123 → Use DELETE /users/123 instead.
🚫 /updateUserName → Use PATCH /users/{id} instead.

✅ Best Practices

✔ Use plural nouns for resources (e.g., /users instead of /user).
✔ Use nouns, not verbs, in endpoints.
✔ Use HTTP methods to define the action.
✔ Use hyphens (-) instead of underscores (_) or camelCase (e.g., /blog-posts).
✔ Nest resources when necessary (e.g., /users/{id}/posts for a user's posts).

---

📌 3. Query Parameters vs. Request Body

✅ Query Parameters (?key=value)

• Used for filtering, searching, sorting, or pagination.
• Example:

  GET /users?name=john&sort=asc&page=2

  Here, name, sort, and page are query parameters.

✅ Request Body

• Used for sending structured data (e.g., JSON).
• Example: Sending data in a POST request:

  POST /users
  Content-Type: application/json

  {
    "name": "John Doe",
    "email": "john@example.com"
  }

🔹 Rule of Thumb:
Use query parameters for filtering & searching.
Use request body for creating & updating resources.

---

📌 4. Organizing Routes in a Backend Framework

🚀 Example: Defining Routes in Express.js

const express = require('express');
const app = express();
app.use(express.json()); // Middleware to parse JSON

// Get all users
app.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'John Doe' }]);
});

// Get a specific user by ID
app.get('/users/:id', (req, res) => {
  res.json({ id: req.params.id, name: 'John Doe' });
});

// Create a new user
app.post('/users', (req, res) => {
  res.status(201).json({ message: 'User created', data: req.body });
});

// Update a user
app.put('/users/:id', (req, res) => {
  res.json({ message: 'User updated', data: req.body });
});

// Delete a user
app.delete('/users/:id', (req, res) => {
  res.json({ message: 'User deleted' });
});

// Start the server
const PORT = 3033;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

---

🎯 Summary

• RESTful APIs should use clear, structured endpoints.
• Use plural nouns and HTTP methods instead of verbs in URLs.
• Use query parameters for filtering/searching and request body for data submission.
• Organize routes in a consistent way inside your backend framework.

---

✅ Next Lesson: JSON and Data Formats in APIs

In the next lesson, you'll learn why JSON is the standard for APIs, how to structure JSON responses, and the differences between JSON and XML. 🚀