Node.js and TypeScript Tutorial: Build a CRUD API

This tutorial shows you how to build a feature-complete API using Node.js, Express, and TypeScript that lets clients perform data operations on resources that describe a restaurant menu. Using TypeScript with Node.js gives you access to optional static type-checking along with robust tooling for large apps and the latest ECMAScript features.

Learn also how to define data models, create a data service, and quickly build modular endpoints. As an option, you can also learn how to secure the API using Auth0.

We tested this tutorial using Node.js

v14.15.1

6.14.8

Get Starts with TypeScript in Node.js

Bootstrap a Node.js Project

Start by creating a project directory anywhere in your system and making it your current directory:

mkdir menu-api
cd menu-api

Next, initialize a Node.js project within the project directory by creating a

package.json

npm init -y

Install Project Dependencies

Your Node.js project requires a couple of dependencies to create a secure Express server with TypeScript. Install them like so:

npm i express dotenv cors helmet

Here's what each of the above packages does in your project:

• express

  : Fast, unopinionated, minimalist web framework for Node.js.

• dotenv

  : Zero-dependency module that loads environment variables from a

  .env

  file into

  process.env

  .

• cors

  : Express middleware to enable CORS with various options.

• helmet

  : Express middleware to secure your apps by setting various HTTP headers, which mitigate common attack vectors.

To use TypeScript, you also need to install a stable version of

typescript

npm i -D typescript

To use TypeScript effectively, you need to install type definitions for the packages you installed previously:

npm i -D @types/node @types/express @types/dotenv @types/cors @types/helmet

When a package doesn't have built-in types, you can get its type definitions through the

@types

v4.17.1

v14.15.1

6.14.8

Initialize TypeScript in Node.js

To help the TypeScript compiler understand your project's structure, you need to create a

tsconfig.json

To easily generate the

tsconfig.json

npx tsc --init

That's all that you need for now to configure your TypeScript project with sensible defaults.

Use Environmental Variables

Instead of using hard-coded configuration variables within files throughout your project, you can define all those variables in a central location and load them into the file modules that need them. Developers working with Node.js commonly define this central location as a hidden file named

.env

touch .env

Populate the

.env

PORT=7000

As seen in the next section, any module of your project can load the variables defined within

.env

dotenv

⚠️ Caution: A

.env

file may contain sensitive information, such as API keys or secrets. Thus, add it to a project's

.gitignore

file to prevent it from being committed to version control.

Create an Express App with TypeScript

To keep your application well-organized, create an

src

mkdir src

Under this

src

index.ts

touch src/index.ts

Add to

index.ts

/**
 * Required External Modules
 */

/**
 * App Variables
 */

/**
 *  App Configuration
 */

/**
 * Server Activation
 */

Next, under the

Required External Modules

.env

dotenv.config()

/**
 * Required External Modules
 */

import * as dotenv from "dotenv";
import express from "express";
import cors from "cors";
import helmet from "helmet";

dotenv.config();

Under the

App Variables

PORT

process.env

number

/**
 * App Variables
 */

if (!process.env.PORT) {
   process.exit(1);
}

const PORT: number = parseInt(process.env.PORT as string, 10);

const app = express();

Under the

App Configuration

/**
 *  App Configuration
 */

app.use(helmet());
app.use(cors());
app.use(express.json());

helmet

helmet()

By mounting

cors()

express.json()

request

body

Finally, under the

Server Activation

/**
 * Server Activation
 */

app.listen(PORT, () => {
  console.log(`Listening on port ${PORT}`);
});

Improve TypeScript Development Workflow

The TypeScript compilation process can increase the bootstrapping time of an application. However, you don't need to recompile the entire project whenever there's a change in its source code. You can set up

ts-node-dev

Start by installing this package to power up your development workflow:

npm i -D ts-node-dev

ts-node-dev

You can create a

dev

package.json

{
  "name": "menu-api",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "ts-node-dev --respawn --pretty --transpile-only src/index.ts"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": { ... },
  "devDependencies": { ... }
}

Let's briefly break down the options that

ts-node-dev

• --respawn

  : Keep watching for changes after the script has exited.

• --pretty

  : Use pretty diagnostic formatter (

  TS_NODE_PRETTY

  ).

• --transpile-only

  : Use TypeScript's faster

  transpileModule

  (

  TS_NODE_TRANSPILE_ONLY

  ).

• src/index.ts

  : This is the application's entry file.

Since

ts-node-dev

node-dev

ts-node

Now, simply run the

dev

npm run dev

If everything is working correctly, you'll see a message indicating that the server is listening for requests on port

7000

You are ready to develop this application further using TypeScript interfaces to define data models, services to manipulate the API resources, and much more.

Model Data with TypeScript Interfaces

$1.10

162

1.10 * 162 = 178.20000000000002

178.20000000000002

110

110 * 162 = 17820

100

17820 / 100 = 178.2

$178.20

Since you are using TypeScript to build your API, you have different options to define and enforce the structure of objects during development. You can use either classes or interfaces to define custom types. You can use interfaces for the menu items as they are not part of the compiled JavaScript bundle, keeping it smaller, and your application won't need instances of a menu item.

To keep your project organized, create an

items

src

mkdir src/items

To start modeling your data, create a file to hold the definition of a

BaseItem

Item

touch src/items/item.interface.ts

Populate

src/items/item.interface.ts

// src/items/item.interface.ts

export interface BaseItem {
  name: string;
  price: number;
  description: string;
  image: string;
}

export interface Item extends BaseItem {
  id: number;
}

There will be scenarios where you only need to assert the item's structure without its

id

POST

PUT

id

BaseItem

Next, create a file to hold the definition of an

Items

Item

touch src/items/items.interface.ts

Populate

src/items/items.interface.ts

// src/items/items.interface.ts

import { Item } from "./item.interface";

export interface Items {
  [key: number]: Item;
}

Create a Node.js Service with TypeScript

A service lets you encapsulate related business logic that you can share across multiple projects. As such, your application can use a service to access and manipulate records from your store.

Create a file to define a service module:

touch src/items/items.service.ts

Populate the

src/items/items.service.ts

// src/items/items.service.ts

/**
 * Data Model Interfaces
 */


/**
 * In-Memory Store
 */


/**
 * Service Methods
 */

Now, under the

Data Model Interfaces

/**
 * Data Model Interfaces
 */

import { BaseItem, Item } from "./item.interface";
import { Items } from "./items.interface";

To keep this tutorial simpler, you are not using an external database to store records. Instead, under the

In-Memory Store

/**
 * In-Memory Store
 */

let items: Items = {
  1: {
    id: 1,
    name: "Burger",
    price: 599,
    description: "Tasty",
    image: "https://cdn.auth0.com/blog/whatabyte/burger-sm.png"
  },
  2: {
    id: 2,
    name: "Pizza",
    price: 299,
    description: "Cheesy",
    image: "https://cdn.auth0.com/blog/whatabyte/pizza-sm.png"
  },
  3: {
    id: 3,
    name: "Tea",
    price: 199,
    description: "Informative",
    image: "https://cdn.auth0.com/blog/whatabyte/tea-sm.png"
  }
};

It's important to note that anytime that you restart the server, Express wipes the in-memory store. However, since you are using

ts-node-dev

Next, create methods to perform read and write operations on the

items

Service Methods

/**
 * Service Methods
 */

export const findAll = async (): Promise<Item[]> => Object.values(items);

export const find = async (id: number): Promise<Item> => items[id];

To simulate the asynchronous nature of read and write operations, all the service methods are

async

findAll

items

find

id

Next, define a method to create a new item in the store:

/**
 * Service Methods
 */

export const findAll = async (): Promise<Items> => {...};

export const find = async (id: number): Promise<Item> => {...};

export const create = async (newItem: BaseItem): Promise<Item> => {
  const id = new Date().valueOf();

  items[id] = {
    id,
    ...newItem,
  };

  return items[id];
};

The

create

BaseItem

id

id

Date

1 January 1970 00:00:00 UTC

Right below, add a method to update an existing store item:

/**
 * Service Methods
 */

export const findAll = async (): Promise<Item[]> => {...};

export const find = async (id: number): Promise<Item> => {...};

export const create = async (newItem: BaseItem): Promise<Item> => {...};

export const update = async (
  id: number,
  itemUpdate: BaseItem
): Promise<Item | null> => {
  const item = await find(id);

  if (!item) {
    return null;
  }

  items[id] = { id, ...itemUpdate };

  return items[id];
};

The

update

id

itemUpdate

id

itemUpdate

null

Finally, define a method to remove an item from the store:

/**
 * Service Methods
 */

export const findAll = async (): Promise<Item[]> => {...};

export const find = async (id: number): Promise<Item> => {...};

export const create = async (newItem: BaseItem): Promise<Item> => {...};

export const update = async (
  id: number,
  itemUpdate: BaseItem
): Promise<Item | null> => {...};

export const remove = async (id: number): Promise<null | void> => {
  const item = await find(id);

  if (!item) {
    return null;
  }

  delete items[id];
};

The

remove

id

You've now completed the creation of a nimble service module using TypeScript and Node.js. Any other project can use the code of this service module as it's not tied to any particular framework. You use it in the next section to create your API controllers.

It's worth mentioning that you could have used a TypeScript class to define and encapsulate the service logic; however, using functions makes testing your service module much easier.

Create Express Controllers

For this application, you'll create endpoints to access an

items

# get all items
GET /api/menu/items

# get a single item using an id parameter
GET /api/menu/items/:id

# create an item
POST /api/menu/items

# update an item using an id parameter
PUT /api/menu/items/:id

# remove an item using an id parameter
DELETE /api/menu/items/:id

You can refer to the WHATABYTE Menu API document to get more details on the signature, input, and response of each endpoint.

Only the

GET

Instead of defining the application routes inside the entry-point file,

index.ts

To start, under the

/src/items

items.router.ts

touch src/items/items.router.ts

When a client application makes a request to your server, Express forwards the request to functions designed to handle that type of request (

GET

POST

items/

Populate

src/items/items.router.ts

/**
 * Required External Modules and Interfaces
 */

/**
 * Router Definition
 */

/**
 * Controller Definitions
 */

// GET items

// GET items/:id

// POST items

// PUT items/:id

// DELETE items/:id

With the template in place, add the following under the

Required External Modules and Interfaces

/**
 * Required External Modules and Interfaces
 */

import express, { Request, Response } from "express";
import * as ItemService from "./items.service";
import { BaseItem, Item } from "./item.interface";

Here, you are importing the

express

Request

Response

You also import all the exported functions from the

items.service

ItemService

Finally, you also import the

Item

Items

ItemService

Next, define an Express router under the

Router Definition

/**
 * Router Definition
 */

export const itemsRouter = express.Router();

Here, you use the

express.Router

You export the

itemsRouter

itemsRouter

Define each controller function by adding the following under the

Controller Definitions

/**
 * Controller Definitions
 */

// GET items

itemsRouter.get("/", async (req: Request, res: Response) => {
  try {
    const items: Item[] = await ItemService.findAll();

    res.status(200).send(items);
  } catch (e) {
    res.status(500).send(e.message);
  }
});

// GET items/:id

itemsRouter.get("/:id", async (req: Request, res: Response) => {
  const id: number = parseInt(req.params.id, 10);

  try {
    const item: Item = await ItemService.find(id);

    if (item) {
      return res.status(200).send(item);
    }

    res.status(404).send("item not found");
  } catch (e) {
    res.status(500).send(e.message);
  }
});

// POST items

itemsRouter.post("/", async (req: Request, res: Response) => {
  try {
    const item: BaseItem = req.body;

    const newItem = await ItemService.create(item);

    res.status(201).json(newItem);
  } catch (e) {
    res.status(500).send(e.message);
  }
});

// PUT items/:id

itemsRouter.put("/:id", async (req: Request, res: Response) => {
  const id: number = parseInt(req.params.id, 10);

  try {
    const itemUpdate: Item = req.body;

    const existingItem: Item = await ItemService.find(id);

    if (existingItem) {
      const updatedItem = await ItemService.update(id, itemUpdate);
      return res.status(200).json(updatedItem);
    }

    const newItem = await ItemService.create(itemUpdate);

    res.status(201).json(newItem);
  } catch (e) {
    res.status(500).send(e.message);
  }
});

// DELETE items/:id

itemsRouter.delete("/:id", async (req: Request, res: Response) => {
  try {
    const id: number = parseInt(req.params.id, 10);
    await ItemService.remove(id);

    res.sendStatus(204);
  } catch (e) {
    res.status(500).send(e.message);
  }
});

The logic of the controllers is compact as they delegate the bulk of their operations to the functions of the

ItemService

ItemService

To complete the setup of your controllers, you need to wire the

itemsRouter

index.ts

Required External Modules

/**
 * Required External Modules
 */

import * as dotenv from "dotenv";
import express from "express";
import cors from "cors";
import helmet from "helmet";
import { itemsRouter } from "./items/items.router";

dotenv.config();

Next, within this file, update the

App Configuration

/**
 *  App Configuration
 */

app.use(helmet());
app.use(cors());
app.use(express.json());
app.use("/api/menu/items", itemsRouter);

The

app.use()

path

callback

itemsRouter

api/menu/items

Test the Express API Endpoints

curl http://localhost:7000/api/menu/items -i

200 OK

curl http://localhost:7000/api/menu/items/2 -i

200 OK

curl -X POST -H 'Content-Type: application/json' -d '{
  "name": "Salad",
  "price": 499,
  "description": "Fresh",
  "image": "https://images.ctfassets.net/23aumh6u8s0i/5pnNAeu0kev0P5Neh9W0jj/5b62440be149d0c1a9cb84a255662205/whatabyte_salad-sm.png"
}' http://localhost:7000/api/menu/items -i

201 Created

curl http://localhost:7000/api/menu/items/ -i

POST

curl -X PUT -H 'Content-Type: application/json' -d '{
  "name": "Spicy Pizza",
  "price": 599,
  "description": "Blazing Good",
  "image": "https://images.ctfassets.net/23aumh6u8s0i/2x1D2KeepKoZlsUq0SEsOu/bee61947ed648848e99c71ce22563849/whatabyte_pizza-sm.png"
}' http://localhost:7000/api/menu/items/2 -i

200 OK

curl http://localhost:7000/api/menu/items/2 -i

200 OK

curl -X DELETE http://localhost:7000/api/menu/items/2 -i

204 No Content

curl http://localhost:7000/api/menu/items/ -i

200 OK

Implement Express Error Handling

In Express, the order in which you declare and invoke middleware is essential for the architecture of your application. What should happen when a client makes a server request that doesn't match any server routes? The ideal behavior is to respond to the client with a

400 Bad Request

A good way to handle this is to create an

HttpException

To continue having an organized application architecture, create a

common

src

mkdir src/common

Within the

src/common

HttpException

touch src/common/http-exception.ts

Populate

src/common/http-exception.ts

// src/common/http-exception.ts

export default class HttpException extends Error {
  statusCode?: number;
  status?: number;
  message: string;
  error: string | null;

  constructor(statusCode: number, message: string, error?: string) {
    super(message);

    this.statusCode = statusCode;
    this.message = message;
    this.error = error || null;
  }
}

With this helper class in place, proceed to create a

middleware

src

mkdir src/middleware

To start, define a middleware function that handles request errors in an

error.middleware.ts

src/middleware

touch src/middleware/error.middleware.ts

Now, populate

src/middleware/error.middleware.ts

// src/middleware/error.middleware.ts

import HttpException from "../common/http-exception";
import { Request, Response, NextFunction } from "express";

export const errorHandler = (
  error: HttpException,
  request: Request,
  response: Response,
  next: NextFunction
) => {
  const status = error.statusCode || error.status || 500;

  response.status(status).send(error);
};

Here, you receive an error of type

HttpException

error.status

error.message

500 Internal Server Error

It's important to note that you must provide four arguments to identify a function as an error-handling middleware function in Express. You must specify the

next

next

Now, also consider that the condition of a route not existing is not considered an error by Express when you use the framework to build a RESTful API. The REST architecture model uses HTTP status codes to respond to the client. A missing resource should not be an error but a condition you need to report to the client.

As such, Express won't call your

errorHandler

employees

curl http://localhost:7000/employees/ -i

Executing the request above returns the following generic HTML response:

HTTP/1.1 404 Not Found
X-DNS-Prefetch-Control: off
X-Frame-Options: SAMEORIGIN
Strict-Transport-Security: max-age=15552000; includeSubDomains
X-Download-Options: noopen
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Access-Control-Allow-Origin: *
Content-Security-Policy: default-src 'none'
Content-Type: text/html; charset=utf-8
Content-Length: 149
Date: Thu, 30 Jan 2020 14:51:01 GMT
Connection: keep-alive
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Error</title>
</head>
<body>
<pre>Cannot GET /employees/</pre>
</body>
</html>

To customize how your app responds to undefined resources, create an additional middleware function to catch

404

src/middleware

not-found.middleware.ts

touch src/middleware/not-found.middleware.ts

Then, add the following code to

src/middleware/not-found.middleware.ts

// src/middleware/not-found.middleware.ts

import { Request, Response, NextFunction } from "express";

export const notFoundHandler = (
  request: Request,
  response: Response,
  next: NextFunction
) => {

  const message = "Resource not found";

  response.status(404).send(message);
};

You now need to wire these middleware functions with your Express app. Open

src/index.ts

Required External Modules

/**
 * Required External Modules
 */

import * as dotenv from "dotenv";
import express from "express";
import cors from "cors";
import helmet from "helmet";
import { itemsRouter } from "./items/items.router";
import { errorHandler } from "./middleware/error.middleware";
import { notFoundHandler } from "./middleware/not-found.middleware";

dotenv.config();

Next, update the

App Configuration

errorHandler

notFoundHandler

/**
 *  App Configuration
 */

app.use(helmet());
app.use(cors());
app.use(express.json());
app.use("/api/menu/items", itemsRouter);

app.use(errorHandler);
app.use(notFoundHandler);

Your application can't reach any routes you define after mounting the

errorHandler

errorHandler

errorHandler

But, as noted earlier,

errorHandler

404

notFoundHandler

Make the following request and observe that you now get your custom

404

Resource not found

curl http://localhost:7000/employees/ -i

http://localhost:7000