Building REST APIs with Express.js

# CHAPTER 14

Building REST APIs with Express.js #

1. Introduction #

2. Learning Objectives #

• Define the constraints of REST architecture.

• Follow proper naming conventions for API routes.

• Align HTTP methods with specific CRUD actions.

• Structure JSON responses uniformly.

3. Beginner-Friendly Explanation #

4. The Rules of REST Naming Conventions #

BAD Examples (Non-RESTful):

• GET /api/getAllArticles

• POST /api/createArticle

• DELETE /api/deleteArticle/5

• PUT /api/updateArticle/5

GOOD Examples (RESTful):

• GET /api/articles (Get all)

• POST /api/articles (Create new)

• GET /api/articles/5 (Get specific article)

• PUT /api/articles/5 (Update specific article)

• DELETE /api/articles/5 (Delete specific article)

*Notice the elegance? It is the exact same URL (/api/articles). The HTTP Method tells the server what action to perform.*

5. Nested Resources #

RESTful Route: GET /api/articles/5/comments *(Translation: Find Article #5, and give me all its Comments).*

Express Implementation:

// Capturing the article ID to query the comments table
app.get('/api/articles/:articleId/comments', async (req, res) => {
    const targetArticleId = req.params.articleId;
    const comments = await Comment.find({ article: targetArticleId });
    res.json(comments);
});

6. The 6 Constraints of REST #

1. 1. Client-Server Architecture: The frontend UI and the backend database logic are completely separate.

1. 2. Statelessness: The server does not remember the client. Every request must contain all the information necessary (like a JWT Token) to process it.

1. 3. Cacheability: Responses should define if they can be cached by the client to improve performance.

1. 4. Uniform Interface: The API uses standard HTTP verbs and predictable URLs (as detailed above).

1. 5. Layered System: The client doesn't know if it's talking directly to the Express server, a load balancer, or a cache.

1. 6. Code on Demand (Optional): The server can send executable code to the client.

7. Standardizing JSON Responses #

The Professional Response Wrapper:

// SUCCESS RESPONSE (Status 200/201)
{
    "status": "success",
    "data": {
        "id": 1,
        "name": "Alice"
    }
}

// ERROR RESPONSE (Status 400/404/500)
{
    "status": "error",
    "message": "User not found in the database",
    "data": null
}

8. Backend Workflow: Versioning #

Always prefix your routes with /api/v1/. app.use('/api/v1/users', userRoutes);

When you make breaking changes a year later, you build /api/v2/users. The old phones keep hitting v1 and functioning perfectly, while the new app update hits v2.

9. Best Practices #

• Use the correct HTTP Status Codes: Don't just return res.json({ error: "Failed" }) while leaving the HTTP Status Code as 200 OK. If it is an error, use a 4xx or 5xx status code. Frontend libraries like Axios rely on the physical HTTP Status Code to trigger their error handling logic.

10. Common Mistakes #

• Using GET to delete data: Beginners sometimes write app.get('/api/users/delete/:id') because it's easy to trigger from a browser address bar. This violates REST principles entirely. Web crawlers (like Googlebot) follow GET links automatically. If Googlebot crawled your site, it would click all the GET links and accidentally delete your entire database! Always use the DELETE HTTP verb.

11. Exercises #

1. 1. Critique this API endpoint: POST /api/v1/user/update-profile/42. Rewrite it to conform perfectly to REST architectural naming conventions.

12. Coding Challenges #

• Challenge: Design the URL endpoints for an E-commerce system. Write down the 5 RESTful URLs and their associated HTTP methods to handle CRUD operations for a "products" resource. Then, write a 6th URL to retrieve all "reviews" for a specific product.

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain the concept of RESTful architecture. What specific constraints must an API adhere to in order to be considered truly RESTful?

• Q: Why is API versioning (e.g., /api/v1/) considered a mandatory best practice in enterprise software development? What disaster does it prevent?

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #