08.Express

Workshop 8 - Express with TypeScript

✔ Learn how to create an HTTP server with express.

✔ Understand the basics and best practices of web development.

✔ Secure your server routes with validation frameworks.

Step 0 : Setup

All the information related to the preparation of the workshop is available in the SETUP.md.

Make sure you have completed its steps before moving on.

Step 01 : Health or Death

To create a web server in TS, you will need the express package.

npm install express @types/express

The purpose of this exercise is to set up a server that exposes two routes /health and /death. With /health returns OK and /death returns BAD_REQUEST.

For this it will be necessary to create and to use the method GET.

In the file src/server.ts:

• Create a new variable app who will instantiate your express server.
• Start the server by listening on the port 8080.
• Define a route GET /health which returns OK
• Define another route GET /death which returns BAD_REQUEST

A basic practice when starting a server is to display a message with the server address so that you can easily access it.

Resources:

• Express
• HTTP Server
• HTTP Methods

Step 02 : Use our routes

We'll need to test those routes, but before let's change the status that sees our route.

💡 A REST API returns data based on what a client requests, but if a client tries to access data that does not belong to them, or does not exist, our API will not be able to send them what they request.

💡 An HTTP code is used to determine the result of a request or to indicate an error to the client. These codes are essential for the proper functioning of HTTP communication services. It is therefore essential to properly setup your server to return the codes adapted to the situation.

Change your route GET /health to always return the status 200 and always display the message OK.

Change your route GET /death to always return the status 400 and always display the message BAD_REQUEST.

If ever during your tests this route does not work anymore, it is because your server is not running or does not work.

It is common to use http-status-codes to explain your status in your code.

Install this dependency with the following command:

npm i http-status-codes

import { StatusCodes } from 'http-status-codes'

Replace your hard-written status-codes with those offered in the package:

res.status(StatusCodes.OK).send("ok");

When we create a route, we want to be able to simply test if it works, and if its implementation has not broken the other route.

It is in this case that Postman can be very useful.

So you will create a Postman collection containing tests on all previously coded routes.
Once your queries are created, you should be able to run a test-suite on your server.

We recommend that you update this collection for all routes of the following exercises.

📚 Resources:

• The main HTTP codes
• Full list of codes
• Using HTTP status in Typescript

About Postman:

• Installing Postman
• Postman Collection
• Postman Test suite
• Postman Environnement

Step 03 : Abuse the good things

In HTTP, the parameters of your request can be expressed in different places:

• body
• parameter
• query
• cookie
• header

To parse data from these different locations, you will need to install middlewares used by express:

npm install body-parser cookie-parser @types/cookie-parser

Your express application will then need to use (use()) on these 2 parsers to apply them to the entire server.

Now all you have to do is create these different routes:

• Create a route GET /repeat-my-query
  • Takes a query parameter message
  • Returns the given message as a parameter
  • If no message is given
    • Set Status 400
    • Return Bad Request
      
      
• Create a route GET /repeat-my-param/:message
  • Takes a parameter message
  • Returns the given message as a parameter
    
    
• Create a route POST /repeat-my-body
  • Returns the message given in the body of the request
  • If the body is empty
    • Set Status 400
    • Return Bad Request
      
      
• Create a route GET /repeat-my-header
  • Look for a header X-Message
  • Returns the message written in it
  • If no message is given
    • Set Status 400
    • Return Bad Request
      
      
• Create a route GET /repeat-my-cookie
  • Look for a cookie message
  • Returns the message given in the cookie
  • If no message is given
    • Set Status 400
    • Return Bad Request

As before, Postman may be useful to test your HTTP routes 🚀

Resources:

• Cookies with Express
• headers with Express

Step 04 : Always think about scaling

💡 Environment variables are variables used by your operating system in many areas. They are visible by typing env in your terminal.

These variables are used when you deploy an application in production to secure passwords and private identifiers. It is therefore essential to know how to use them in your code 😉

For this, we will use the package env-var which allows you to automatically load environment variables from a file:

npm i env-var

Next, create a file .envrc which will export the following environment variables:

• SERVER_PORT=8080
• HELLO_MESSAGE=world

⚠️ You will also need to install direnv to load the variables into your environment with the direnv allow.

In the file src/serverConfig.ts, retrieve these two environment variables and export them.

It is common in an API to have a file specific to the configuration, it allows you to keep a clean and constant architecture.

Adapt the express server code to use the port set in the your environment, and if it's not set, use the port 8080.

Create a route GET /hello to use the variable HELLO_MESSAGE as a response.

• If the variable is not present:
  • Set Status 404
  • Return No Message Defined

💡 If your .envrc contains private variables, it is imperative not to push it on the repo.
The best practice is to create a envrc.example file containing the various variables but without their values, in order to indicate what will subsequently be needed, then fill it in and rename it to .envrc.

It is important to think from the beginning of the application about integrating your server into a web architecture by placing as many variables as possible that may change in the environment 💾

Resources :

• env-var
• direnv

Step 05 : Testing time

Have you tested the new routes you created?

If you did, congratulations, that's a good habit to have, you can move on to the next step 🥳

Else, enrich your test collection with tests for your new routes 😉

Resources:

• Postman Collection
• Postman Test suite
• Postman Environnement

Step 06 : The bodyguards of the servers

On the web, it's important to know which types of data are sent to your API.
This allows you to have a stable and secure code.

Send an empty body to a route reading data from it, you should get an error back if you didn't perform checks.
This kind of error is not acceptable for an API.

But fortunately, to ensure the security of an API, there is a system called middleware.

Here is the structure of a custom middleware in an express API:

const myMiddleware = (req: Request, res: Response, next: NextFunction) => {
}

💡 Middlewares can also be used to set up a logger, manage permissions etc.

• Create a route /private.
• You can see that in the second parameter we have the middleware

app.get("/private", middleware, (_req, res) => {
    console.log("Password is good");
    res.status(StatusCodes.OK);
});

Update .envrc

Create a new variable in your .envrc

AUTHORIZATION_PORT=mykey

⚠️ Your objective is to verify the value of the user in his headers, which must be equal to your variable AUTHORIZATION_PORT

Write a middleware

Create a file middlewares.ts, write a middleware that will check the headers of the /private route with as key authorization.
In case of invalid headers, return the status 400 and the reason for the refusal.

Resources:

• Middleware

To go further

Here is a list of links if you want to learn more about Typescript APIs:

• How to Write Useful API Documentation
• How to work with asynchronicity
• Test your app with insomnia
• Other NodeJs framework
• NestJS, a progressive Node framework
• Centralized error management

Organization

🚀 Don't hesitate to follow us on our different networks, and put a star 🌟 on PoC's repositories.