[mabel] Shift descriptions from express basics to individual topics

Author: mabelleeyanhwa

docs/backend-web-development/express-basics.md

@@ -33,123 +33,6 @@ const server = app.listen(PORT, () => {
 });
 ```
 
-## Routing
-
-Routing is to add a handler function (a callback function) that is called when a user visit a particular route, for example the homepage `/` or `/books`. When you listen for connections on a route in Express, the handler function will be invoked when a request comes in.
-
-The request object and response object are passed to the handler function when the handler function is called.
-
-```js
-app.get("/", (req, res) => {
-  res.send("Hello World!");
-});
-```
-
-Routing is described in detail on another page.
-
-## Request object
-
-The Request object (req) passed to a callback function holds all the HTTP request information that was sent to your server like query strings.
-
-It starts off as an instance of _http.IncomingMessage_, a core Node object. Express then extends the object to add further functionality.
-
-These are the commonly used properties of the request object:
-
-- `req.params`
-  Added by Express. An array containing named route parameters. This will be further explained below.
-
-- `req.query`
-  Added by Express. An object containing querystring parameters as name/value pairs. This will also be further explained below.
-
-- `req.url`
-  The request URL string.
-
-- `req.method`
-  The HTTP method (GET, POST, PUT, DELETE).
-
-These could be used for debugging.
-
-```js
-console.log("Method: " + req.method);
-console.log("Path: " + req.url);
-```
-
-You are unable to access the body of a request with `req.body` if the body is not parsed yet. This will be further explained in the [parsing request body](express-parsing-request-body) page.
-
-## Response object
-
-The Response object (res) passed to a callback function holds information that your server will respond with when the connection is ended with the client.
-
-It starts off as an instance of _http.ServerResponse_, a core Node object. The res object is an enhanced version of the response object found in Node.js.
-
-These are the commonly used properties or methods of the response object:
-
-- `res.send()`
-  Added by Express. Use it to send a response back to the client.
-
-- `res.json()`
-  Added by Express. Use it to send a JSON response back to the client.
-
-- `res.status(statusCode)`
-  Added by Express. Use it to set the status code of the response.
-
-- `res.sendStatus(statusCode)`
-  Added by Express. Shortcut for the above and sending the string representation of the status code as the response body.
-
-- `res.end()`
-  Send an empty response back to the client without any body.
-
-## Middleware
-
-Middleware functions are run by Express.js on the request before passing it on to the final handler function.
-
-The request object, response object and the `next` function are passed to each middleware function. To move on to the `next` function to be run in the stack (could be a middleware function or handler function), the `next` function needs to be called.
-
-```js
-app.use(function(req, res, next) {
-  console.log("Method: " + req.method);
-  console.log("Path: " + req.url);
-  next();
-}
-```
-
-Middleware is described in detail on another page.
-
-## Routers
-
-From Express.js [documentation for Router](https://expressjs.com/en/guide/routing.html#express-router),
-
-> Use the express.Router class to create modular, mountable route handlers. A Router instance is a complete middleware and routing system; for this reason, it is often referred to as a “mini-app”.
-
-In other words, routers are just like the root level app you created using `express()` so much so that they are mini-apps.
-
-You can mount them to an app. For example, a router can be mounted to the `/empty` route of an app.
-
-```js
-const router = express.Router();
-
-router.get("/", (res, req) => res.end());
-router.post("/", (res, req) => res.end());
-
-app.use("/empty", router);
-```
-
-## Layer stack
-
-How does all these work together?
-
-When we call `app.use` or `app.get` etc, we are adding a layer into the app or router.
-Every app or router will have a layer stack - a stack of layers where every _Layer_ has its own _path_.
-
-This layer can be a
-
-- middleware
-- route
-- error handler
-- another router
-
-See this [Medium article](https://medium.com/@viral_shah/express-middlewares-demystified-f0c2c37ea6a1) if you are curious to understand how this layer stack works.
-
 ## Testing the server
 
 ### cURL

docs/backend-web-development/express-error-handling.md

@@ -40,7 +40,7 @@ Within an error handler, you typically need to do one of two things:
 - call `next(err)` to pass the execution to the next error handler
 
 ```js
-app.use(function(err, req, res, next) {
+app.use(function (err, req, res, next) {
   res.status(500);
   res.send(
     `Error: ${err} </br>
@@ -67,7 +67,7 @@ app.get("/", (req, res) => {
 Return the correct status code in the response header if `err.code` is defined. Else we will default to the error code `500`.
 
 ```js
-app.use(function(err, req, res, next) {
+app.use(function (err, req, res, next) {
   res.status(err.code || 500);
   res.send(
     `Error: ${err} </br>
@@ -84,7 +84,7 @@ Refer to the script: [Express.js playground: error_handler_example_3](https://gi
 If you call an asynchronous API in a route handler and you would like to handle errors returned/thrown by those asynchronous operations, you just need to call `next(err)` when some error happens. That is, you call the `next` callback (which is an argument of every middleware and route handler) with an instance of _Error_.
 
 ```js
-app.get("/", function(req, res, next) {
+app.get("/", function (req, res, next) {
   // assume some asynchronous error happens because of an network issue
   const err = new Error("Unexpected network error");
   next(err);
@@ -94,15 +94,15 @@ app.get("/", function(req, res, next) {
 Let's add a route handler that will not be called because it will be skipped when the error is thrown.
 
 ```js
-app.get("/", function(req, res, next) {
+app.get("/", function (req, res, next) {
   console.log("You should not see this line in the console 😡");
 });
 ```
 
 Add a custom error handler that will catch the error and then pass it on to the next error handler.
 
 ```js
-app.use(function(err, req, res, next) {
+app.use(function (err, req, res, next) {
   if (err.message === "Unexpected network error") {
     console.log("I don't know how to handle network error. Pass it on.");
     next(err);
@@ -116,7 +116,7 @@ app.use(function(err, req, res, next) {
 Add a final custom error handler that will return a response to the client.
 
 ```js
-app.use(function(err, req, res, next) {
+app.use(function (err, req, res, next) {
   res.status(500);
   res.send({ error: "internal server error" });
 });
@@ -127,8 +127,8 @@ An example of error handling with an asynchronous API is as follows:
 ```js
 const fs = require("fs");
 
-app.get("/", function(req, res, next) {
-  fs.readFile("/file-does-not-exist", function(err, data) {
+app.get("/", function (req, res, next) {
+  fs.readFile("/file-does-not-exist", function (err, data) {
     if (err) {
       next(err);
     } else {
@@ -145,8 +145,8 @@ To see the value of having error handling middleware, imagine having the followi
 ```js
 const fs = require("fs");
 
-app.get("/", function(req, res, next) {
-  fs.readFile("/file-does-not-exist", function(err, data) {
+app.get("/", function (req, res, next) {
+  fs.readFile("/file-does-not-exist", function (err, data) {
     if (err) {
       res.status(500).json({ error: error.toString() });
     } else {
@@ -192,3 +192,19 @@ You can see now that error handling middleware allows you to consolidate error h
 ## Best practices
 
 As a best practice, we should always declare a default error handler for all requests, to ensure we handle all unforeseeable error scenarios. You will define error-handling middleware last, after other app.use() and routes calls.
+
+## Layer stack
+
+How does middleware, route, error handler, routers work together?
+
+When we call `app.use` or `app.get` etc, we are adding a layer into the app or router.
+Every app or router will have a layer stack - a stack of layers where every _Layer_ has its own _path_.
+
+This layer can be a
+
+- middleware
+- route
+- error handler
+- another router
+
+See this [Medium article](https://medium.com/@viral_shah/express-middlewares-demystified-f0c2c37ea6a1) if you are curious to understand how this layer stack works.

docs/backend-web-development/express-middleware.md

@@ -1,12 +1,27 @@
 # Express.js middleware
 
-Middlewares are all the functions that are invoked by the Express.js routing layer before the final handler function is called. They sit in the middle between a raw request and the final intended route. We often refer to these functions as the middleware stack since they are always invoked in the order they are added.
+Middlewares are all the functions that are invoked by the Express.js routing layer on the request before the final handler function is called. They sit in the middle between a raw request and the final intended route. We often refer to these functions as the middleware stack since they are always invoked in the order they are added.
+
 The following diagram shows how the middlewares work together in a _pipeline_ like water flowing in a pipe:
 
 <img src="backend-web-development/_media/middleware.png" alt="how middleware work together" width="700"/>
 
 (image source: https://manuel-rauber.com)
 
+You could also imagine that it is a factory. For the request "assembly line", the request is passed from one middleware to another before it reaches the final handler function where the response is finally sent back to the client.
+
+## Example
+
+The request object, response object and the `next` function are passed to each middleware function. To move on to the `next` function to be run in the stack (could be a middleware function or handler function), the `next` function needs to be called.
+
+```js
+app.use(function(req, res, next) {
+  console.log("Method: " + req.method);
+  console.log("Path: " + req.url);
+  next();
+}
+```
+
 ## Why do we need middlewares?
 
 Middlewares allow us to put logic with cross-cutting concerns (i.e. the logic that can be shared by multiple route handlers) into a common place and avoid duplicating the same logic in each route handler.
@@ -60,7 +75,7 @@ Refer to the script: [Express.js playground: middleware_example_1](https://githu
 Add a middleware function that will be called for all routes. It has no mount path.
 
 ```js
-app.use(function(req, res, next) {
+app.use(function (req, res, next) {
   console.log("common middleware function was called!");
   next();
 });
@@ -69,7 +84,7 @@ app.use(function(req, res, next) {
 Add a middleware function that will only be called if a request goes to the `/users` route.
 
 ```js
-app.use("/users", function(req, res, next) {
+app.use("/users", function (req, res, next) {
   console.log("middleware function for /users was called!");
   next();
 });
@@ -78,7 +93,7 @@ app.use("/users", function(req, res, next) {
 Add a middleware function that will only be called if a POST request goes to the `/users` route.
 
 ```js
-app.post("/users", function(req, res, next) {
+app.post("/users", function (req, res, next) {
   console.log("second middleware function for /users was called!");
   next();
 });
@@ -87,7 +102,7 @@ app.post("/users", function(req, res, next) {
 Add a middleware function that will only be called if a GET request goes to the `/users` route.
 
 ```js
-app.get("/users", function(req, res, next) {
+app.get("/users", function (req, res, next) {
   console.log("third middleware function for /users was called!");
   next();
 });

docs/backend-web-development/express-routers.md

@@ -2,7 +2,20 @@
 
 For a very small app, we can define all the API endpoints in one file, like what we did in the previous examples. However, as our application grows, it's a good idea to break the application into smaller modules. In terms of the API end points, it would be better to group API endpoints by their nature.
 
-Each Router is like a mini-app or subapplication, which means it can contain its own API endpoints, together with many other things such as middleware and error handlers, as you will notice later.
+Use the express.Router class to create modular, mountable route handlers.Each Router is like a mini-app or subapplication, which means it can contain its own API endpoints, together with many other things such as middleware and error handlers, as you will notice later.
+
+## Example
+
+You can mount them to an app. For example, a router can be mounted to the `/empty` route of an app.
+
+```js
+const router = express.Router();
+
+router.get("/", (res, req) => res.end());
+router.post("/", (res, req) => res.end());
+
+app.use("/empty", router);
+```
 
 ## Implementation
 
@@ -14,8 +27,6 @@ const router = express.Router();
 
 The difficult part is deciding / designing what to put in it.
 
-## Exercises
-
 For example, if we are implementing an API for a library system, the API endpoint for users and books can be put into their own routers / modules. We can refactor our basic example to use routers.
 
 ### Basic organisation of routes