TypeScript: Building a Simple REST API with Express.js

Written by

learnmodernjavascript

in

In today’s interconnected digital landscape, APIs (Application Programming Interfaces) are the backbone of modern web applications. They allow different software systems to communicate and exchange data seamlessly. If you’re a developer eager to build your own web services, understanding how to create a REST API is a crucial skill. This tutorial will guide you through building a simple, yet functional, REST API using TypeScript and Express.js, a popular Node.js framework. We’ll cover everything from setting up your development environment to handling HTTP requests and responses, all while ensuring type safety with TypeScript.

Why TypeScript and Express.js?

Before we dive in, let’s discuss why we’re choosing these tools. TypeScript, a superset of JavaScript, adds static typing to your code. This means you can catch errors early in the development process, improve code readability, and benefit from better tooling support (like autocompletion). Express.js, on the other hand, is a fast, unopinionated, and minimalist web framework for Node.js. It provides a robust set of features for building web applications, including routing, middleware, and more.

Prerequisites

To follow along with this tutorial, you’ll need the following:

  • Node.js and npm (Node Package Manager) installed on your system.
  • A basic understanding of JavaScript.
  • A code editor of your choice (e.g., VS Code, Sublime Text, Atom).

Setting Up Your Project

Let’s get started by creating a new project directory and initializing it with npm. Open your terminal or command prompt and run the following commands:

mkdir typescript-express-api
cd typescript-express-api
npm init -y

This will create a new directory, navigate into it, and initialize a `package.json` file with default settings. Next, we’ll install the necessary packages:

npm install express typescript @types/express --save-dev

Here’s what each package does:

  • `express`: The Express.js framework.
  • `typescript`: The TypeScript compiler.
  • `@types/express`: Type definitions for Express.js, allowing TypeScript to understand the framework’s structure and provide type checking.

Now, let’s set up TypeScript configuration. Create a `tsconfig.json` file in your project root with the following content:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Let’s break down the `tsconfig.json` options:

  • `target`: Specifies the JavaScript version to compile to (ES2016 is a good starting point).
  • `module`: Defines the module system (CommonJS is suitable for Node.js).
  • `outDir`: Sets the output directory for compiled JavaScript files (`./dist`).
  • `rootDir`: Indicates the root directory of your source files (`./src`).
  • `strict`: Enables strict type checking.
  • `esModuleInterop`: Enables interoperability between CommonJS and ES modules.
  • `skipLibCheck`: Skips type checking of declaration files.
  • `forceConsistentCasingInFileNames`: Enforces consistent casing in filenames.
  • `include`: Specifies which files to include in the compilation.

Next, create a `src` directory and an `index.ts` file inside it. This is where we’ll write our API logic.

Building Your First API Endpoint

Open `src/index.ts` and add the following code:

import express, { Request, Response } from 'express';

const app = express();
const port = 3000;

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, TypeScript and Express!');
});

app.listen(port, () => {
  console.log(`Server is running at http://localhost:${port}`);
});

Let’s examine the code:

  • We import `express` and the `Request` and `Response` types from the `express` module.
  • We create an Express application instance using `express()`.
  • We define a route handler for the root path (`/`) using `app.get()`. This handler takes a request (`req`) and a response (`res`) object as arguments.
  • Inside the route handler, we use `res.send()` to send a simple response back to the client.
  • We start the server using `app.listen()`, specifying the port number (3000 in this case) and a callback function that logs a message to the console when the server is running.

Now, let’s compile the TypeScript code and run the server. In your terminal, run the following commands:

tsc
node dist/index.js

The `tsc` command compiles your TypeScript code into JavaScript, and the `node dist/index.js` command runs the compiled JavaScript file. Open your web browser and go to `http://localhost:3000`. You should see the message “Hello, TypeScript and Express!” displayed in the browser.

Adding More API Endpoints

Let’s expand our API by adding more endpoints. We’ll create endpoints to handle different HTTP methods (GET, POST, PUT, DELETE) and work with some sample data.

First, let’s define a simple data structure. Create a file named `src/models/item.ts` with the following content:

export interface Item {
  id: number;
  name: string;
  description: string;
}

This defines an `Item` interface with `id`, `name`, and `description` properties. Now, let’s create a basic in-memory data store. In `src/index.ts`, add the following code before the `app.get(‘/’)` route:

import express, { Request, Response } from 'express';
import { Item } from './models/item';

const app = express();
const port = 3000;

// Middleware to parse JSON request bodies
app.use(express.json());

let items: Item[] = [
  { id: 1, name: 'Item 1', description: 'Description of item 1' },
  { id: 2, name: 'Item 2', description: 'Description of item 2' },
];

Here’s what we’ve added:

  • We import the `Item` interface.
  • We create an in-memory `items` array to store our data.
  • We add `app.use(express.json())`. This is middleware that parses incoming requests with JSON payloads and makes the parsed data available in `req.body`.

Now, let’s add the API endpoints:

// GET /items - Get all items
app.get('/items', (req: Request, res: Response) => {
  res.json(items);
});

// GET /items/:id - Get a specific item by ID
app.get('/items/:id', (req: Request, res: Response) => {
  const id = parseInt(req.params.id, 10);
  const item = items.find(item => item.id === id);

  if (item) {
    res.json(item);
  } else {
    res.status(404).json({ message: 'Item not found' });
  }
});

// POST /items - Create a new item
app.post('/items', (req: Request, res: Response) => {
  const newItem: Item = req.body;
  newItem.id = items.length + 1;
  items.push(newItem);
  res.status(201).json(newItem);
});

// PUT /items/:id - Update an item
app.put('/items/:id', (req: Request, res: Response) => {
  const id = parseInt(req.params.id, 10);
  const updatedItem: Item = req.body;
  const itemIndex = items.findIndex(item => item.id === id);

  if (itemIndex !== -1) {
    items[itemIndex] = { ...items[itemIndex], ...updatedItem };
    res.json(items[itemIndex]);
  } else {
    res.status(404).json({ message: 'Item not found' });
  }
});

// DELETE /items/:id - Delete an item
app.delete('/items/:id', (req: Request, res: Response) => {
  const id = parseInt(req.params.id, 10);
  const itemIndex = items.findIndex(item => item.id === id);

  if (itemIndex !== -1) {
    items.splice(itemIndex, 1);
    res.status(204).send(); // 204 No Content
  } else {
    res.status(404).json({ message: 'Item not found' });
  }
});

Let’s break down these new endpoints:

  • **GET /items:** Retrieves all items from the `items` array and returns them as JSON.
  • **GET /items/:id:** Retrieves a specific item based on its ID. The `id` is extracted from the URL parameters (`req.params.id`). If the item is found, it’s returned as JSON; otherwise, a 404 Not Found error is returned.
  • **POST /items:** Creates a new item. The new item’s data is expected in the request body (`req.body`). The item is added to the `items` array, and the new item with its assigned ID is returned with a 201 Created status code.
  • **PUT /items/:id:** Updates an existing item. The `id` of the item to update is extracted from the URL parameters. The updated item data is expected in the request body. If the item is found, it’s updated in the `items` array, and the updated item is returned as JSON; otherwise, a 404 Not Found error is returned.
  • **DELETE /items/:id:** Deletes an item. The `id` of the item to delete is extracted from the URL parameters. If the item is found, it’s removed from the `items` array, and a 204 No Content status code is returned.

Recompile your code (`tsc`) and restart the server (`node dist/index.js`). Now, you can test these endpoints using a tool like Postman, Insomnia, or curl. For example, to get all items, you would send a GET request to `http://localhost:3000/items`. To create a new item, you would send a POST request to the same URL with a JSON payload in the request body, such as `{“name”: “New Item”, “description”: “Description of new item”}`.

Error Handling

Robust error handling is critical for any API. While our example API is simple, let’s add some basic error handling to demonstrate the concept. We’ll add a middleware function to handle errors that occur during request processing.

Add the following code to `src/index.ts` after the route definitions:

// Error handling middleware
app.use((err: Error, req: Request, res: Response, next: Function) => {
  console.error(err.stack);
  res.status(500).json({ message: 'Internal Server Error' });
});

This middleware function takes four arguments: `err`, `req`, `res`, and `next`. It’s crucial to include all four arguments to signal to Express that this is an error-handling middleware. The function logs the error stack to the console and sends a 500 Internal Server Error response to the client. This is a simplified example; in a production environment, you would likely implement more sophisticated error logging and handling.

Input Validation

Input validation is another important aspect of building a secure and reliable API. It ensures that the data received from the client is in the expected format and meets specific criteria. This prevents unexpected behavior, data corruption, and potential security vulnerabilities.

Let’s add some basic input validation to our `POST /items` and `PUT /items/:id` endpoints. We’ll use a simple check to ensure that the `name` and `description` properties are present in the request body.

Modify the `POST /items` endpoint in `src/index.ts` to include the following validation:

// POST /items - Create a new item
app.post('/items', (req: Request, res: Response) => {
  const newItem: Item = req.body;

  if (!newItem.name || !newItem.description) {
    return res.status(400).json({ message: 'Name and description are required' });
  }

  newItem.id = items.length + 1;
  items.push(newItem);
  res.status(201).json(newItem);
});

Now, let’s modify the `PUT /items/:id` endpoint to include validation:

// PUT /items/:id - Update an item
app.put('/items/:id', (req: Request, res: Response) => {
  const id = parseInt(req.params.id, 10);
  const updatedItem: Item = req.body;

  if (!updatedItem.name && !updatedItem.description) {
    return res.status(400).json({ message: 'Either name or description must be provided for update' });
  }

  const itemIndex = items.findIndex(item => item.id === id);

  if (itemIndex !== -1) {
    items[itemIndex] = { ...items[itemIndex], ...updatedItem };
    res.json(items[itemIndex]);
  } else {
    res.status(404).json({ message: 'Item not found' });
  }
});

In these examples, we check if the `name` and `description` properties are present in the request body for the `POST` request. For the `PUT` request, we ensure that at least one of the `name` or `description` properties is provided. If the validation fails, a 400 Bad Request error is returned with an appropriate message. In a real-world application, you might use a more robust validation library like `joi` or `class-validator` to handle more complex validation rules.

Testing Your API

Testing your API is crucial to ensure it functions correctly. You can test your API manually using tools like Postman or Insomnia, or you can write automated tests using a testing framework like Jest or Mocha. For this tutorial, we’ll demonstrate manual testing using Postman.

1. **Install Postman:** If you don’t already have it, download and install Postman from the official website ([https://www.postman.com/](https://www.postman.com/)).

2. **Create a New Request:** Open Postman and click on the “New” button to create a new request.

3. **Configure the Request:**

* **Method:** Select the appropriate HTTP method (GET, POST, PUT, DELETE) from the dropdown menu.
* **URL:** Enter the API endpoint URL (e.g., `http://localhost:3000/items`).
* **Headers:** For POST and PUT requests, you’ll need to set the `Content-Type` header to `application/json`. You can add this header in the “Headers” tab.
* **Body:** For POST and PUT requests, you’ll need to provide a JSON payload in the “Body” tab. Select “raw” and then choose “JSON” from the dropdown menu. Enter your JSON data.

4. **Send the Request:** Click the “Send” button to send the request to your API.

5. **View the Response:** Postman will display the API’s response, including the status code, headers, and body. Verify that the response is as expected.

Here’s how you’d test each endpoint:

  • **GET /items:** Send a GET request to `http://localhost:3000/items`. You should receive a JSON array of all items.
  • **GET /items/:id:** Send a GET request to `http://localhost:3000/items/1` (replace `1` with an existing item ID). You should receive the item with that ID.
  • **POST /items:** Send a POST request to `http://localhost:3000/items` with a JSON payload in the body, such as:
{
  "name": "New Item",
  "description": "Description of new item"
}

You should receive a 201 Created status code and the newly created item as a response.

  • **PUT /items/:id:** Send a PUT request to `http://localhost:3000/items/1` (replace `1` with an existing item ID) with a JSON payload in the body, such as:
{
  "name": "Updated Item"
}

You should receive a 200 OK status code and the updated item as a response.

  • **DELETE /items/:id:** Send a DELETE request to `http://localhost:3000/items/1` (replace `1` with an existing item ID). You should receive a 204 No Content status code.

By testing each endpoint thoroughly, you can ensure that your API is functioning correctly and meets your requirements.

Common Mistakes and How to Fix Them

Building a REST API can be tricky, and it’s easy to make mistakes. Here are some common pitfalls and how to avoid them:

  • **Incorrect HTTP Methods:** Using the wrong HTTP method for an operation. For example, using GET to create a new resource (should be POST). Make sure you understand the correct use of GET, POST, PUT, DELETE, and PATCH.
  • **Missing or Incorrect Content-Type Header:** For POST and PUT requests, forgetting to set the `Content-Type` header to `application/json`. This can cause the server to fail to parse the request body.
  • **Not Handling Errors:** Failing to implement proper error handling. This can lead to unhelpful error messages and a poor user experience. Always include error handling middleware.
  • **Lack of Input Validation:** Not validating user input. This can lead to security vulnerabilities and unexpected behavior. Implement input validation to ensure data integrity.
  • **Incorrect Routing:** Defining incorrect routes or route parameters. Double-check your routes to ensure they match the intended functionality.
  • **Forgetting to Compile:** Forgetting to recompile your TypeScript code after making changes. Always run `tsc` before restarting your server.
  • **Inadequate Testing:** Not thoroughly testing your API endpoints. Use tools like Postman or write automated tests to ensure your API functions as expected.
  • **Not Using TypeScript Types:** Not leveraging the benefits of TypeScript types. Using `any` excessively defeats the purpose of TypeScript. Define interfaces and types to ensure type safety.

Key Takeaways

  • REST APIs are the backbone of modern web applications.
  • TypeScript enhances code quality and maintainability with static typing.
  • Express.js provides a flexible framework for building APIs.
  • Proper error handling and input validation are crucial for robust APIs.
  • Thorough testing is essential to ensure API functionality.

FAQ

Here are some frequently asked questions about building REST APIs with TypeScript and Express.js:

  1. **What is the difference between GET, POST, PUT, and DELETE?**
    • `GET`: Retrieves data from a server.
    • `POST`: Creates new data on a server.
    • `PUT`: Updates existing data on a server (replaces the entire resource).
    • `DELETE`: Deletes data from a server.
  2. **How do I handle authentication and authorization in my API?**

    Authentication verifies the identity of a user, while authorization determines what a user can access. Common approaches include using JWT (JSON Web Tokens), OAuth, or session-based authentication. Implementing authentication and authorization often involves using middleware to protect specific routes.

  3. **How can I deploy my API?**

    You can deploy your API to various platforms, such as Heroku, AWS, Google Cloud Platform, or a dedicated server. You’ll typically need to package your application, configure the server environment, and handle environment variables.

  4. **What is middleware, and why is it important?**

    Middleware functions are functions that have access to the request object (`req`), the response object (`res`), and the next middleware function in the application’s request-response cycle. They can perform tasks such as logging, authentication, error handling, and parsing request bodies. Middleware is essential for building modular and maintainable APIs.

  5. **How can I improve the performance of my API?**

    You can improve API performance by optimizing database queries, caching data, using efficient data formats (e.g., JSON), and implementing techniques like load balancing and horizontal scaling.

This tutorial has provided a solid foundation for building a REST API with TypeScript and Express.js. You’ve learned how to set up your project, define API endpoints, handle HTTP requests and responses, implement error handling, and perform basic input validation. You’ve also seen how to test your API and learned about common mistakes and how to fix them. Remember, building APIs is an iterative process. Keep practicing, experimenting, and exploring new features. As you build more complex APIs, you’ll gain a deeper understanding of the concepts and techniques discussed here. There are many more advanced topics to explore, such as database integration, authentication, authorization, and API documentation. With the knowledge you’ve gained, you’re well-equipped to embark on your API development journey. By continuing to learn and apply these principles, you’ll be able to create powerful and efficient APIs that serve as the foundation for your web applications. Happy coding!

More posts