How I structure my REST APIs
Tags: node, express, beginners, showdev
Published: 2018-10-03 15:37:28

---
title: How I structure my REST APIs
published: true
description: 
tags: nodejs, express, beginners, showdev
---

This post was originally published on my [blog](https://larswaechter.dev/blog/nodejs-rest-api-structure/).

---

When I started using [Node.js](https://nodejs.org/en/) for building REST APIs on the server side, I struggled a lot with the same question over and over again:

> How should the folder structure look like?

Obviously there’s **no perfect or 100% correct** answer to this question but after reading some articles regarding this topic, I found a folder structure and architecture that fit my needs quite well. So today I’d like to show you how I structure and organize my Node.js REST APIs.

I also published a GitHub [repository](https://github.com/larswaechter/expressjs-api) including an example application which you can use as template for your own project.

One thing to mention is that I use [Express.js](https://expressjs.com/de/) as web-framework and [TypeORM](https://typeorm.io/#/) as an ORM. It shouldn't be that hard to apply this folder structure for other frameworks too.

The architecture is mostly **component based** what makes it much easier to request only the data we really need. For example we have a `User` component that contains all information about users.

Let's start with the `root` directory.

### Directory: root

```
expressjs-api
└───db
│
└───dist
│
└───logs
│
└───node_modules
│
└───src
│
│   README.md
│   ...
```

This structure is nothing special and shouldn’t be new to you. It’s actually a basic Node.js setup. The interesting part here is the content of the `src` folder which this post is about.

So what do we have in here?

```
expressjs-api
└───src
   │
   └───api
   │   │
   │   └───components
   │   │
   │   └───middleware
   │   │
   │   │   routes.ts
   │   │   server.ts
   │
   └───config
   │
   └───services
   │
   └───test
   |
   │   app.ts
```

From here on, we'll go top-down through the files / directories and I'll explain each one. Let’s start with the `api` directory, the most important part of the application.

### Directory: src/api/components

```
expressjs-api
└───src
    │
    └───api
        │
        └───components
            │
            └───article
            │
            └───auth
            │
            └───country
            │
            └───user
            │   helper.ts
            │   index.ts
```

Here we have the heart of our component based Node API. Each component has its own **routes**, **controller**, **model**, **repository**, **policies**, **tests** and **templates**.

Let’s step into the `User` component and have a look.

### Directory: src/api/components/user

```
expressjs-api
└───src
    │
    └───api
        │
        └───components
            │
            └───user
                │
                └───services
                |   │   mail.ts
                └───templates
                |   │   confirmation.html
                |   |   invitation.html
                │   controller.ts
                │   model.ts
                │   policy.json
                │   repository.ts
                │   routes.ts
                │   user.spec.ts
```

As you can see a component consists of the files I just mentioned before. Most of them represents a **single class** that is exported. Of course, you can add here more component specific stuff.

Since I have multiple components and their classes have the same structure most of the time, I also create **interfaces** that are implemented in the classes. This helps me to keep the components’ structure straight.

Moreover, we have the `services` directory here which includes local component services like `mail` for example. Those interhite from the global services.

The `templates` directory includes mail HTML templates for the given component. For dynamically rendering HTML code I highly recommend [ejs](https://www.npmjs.com/package/ejs).

#### controller.ts

The controller class handles incoming requests and sends the response data back to the client. It uses the `repository` class to interact with the database. Request validation happens via middleware few steps before

A shortened example:

```ts
export class UserController {
  private readonly repo: UserRepository = new UserRepository()

  async readUser(
    req: Request,
    res: Response,
    next: NextFunction
  ): Promise<Response | void> {
    try {
      const { userID } = req.params

      const user: User | undefined = await this.repo.read({
        where: {
          id: +userID,
        },
      })

      return res.json(user)
    } catch (err) {
      return next(err)
    }
  }
}
```

#### model.ts

The model represents the database model for its component. In my case it’s a [TypeORM](https://typeorm.io/) class. Mostly it’s used by the `repository` classes.

#### policy.json

This json file includes the access rights for each user-role for the given component. It's part of a [access control list](https://de.wikipedia.org/wiki/Access_Control_List) based system.

Example:

```json
{
  "Admin": [{ "resources": "user", "permissions": "*" }],
  "User": [{ "resources": "user", "permissions": ["read"] }]
}
```

#### repository.ts

The repository class acts like a wrapper for the database. Here we read and write data to the database. Furthermore, we can implement caching for example.

You can import the `repository` class into any other file and query the data for this component from the database. Moreover, it prevents us from writing redundant code since we don't have to rewrite the SQL statements multiple times.

Since most component repositories need the same basic access methods like `readAll`, `read`, `save` and `delete` I use a generic parent class that includes all these methods. This saves a lot of code.

See [AbsRepository](https://github.com/larswaechter/expressjs-api/blob/main/src/api/components/helper.ts) for the implementation.

#### routes.ts

Here we define the API **endpoints** for the corresponding component and assign the `controller` methods to them. Moreover we can add more stuff like

- authorization (e.g. JWT)
- permission checking (ACL)
- request body validation
- component specific middleware in here.

A shortened Example:

```ts
class UserRoutes implements IComponentRoutes<UserController> {
  readonly name: string = "user"
  readonly controller: UserController = new UserController()
  readonly router: Router = Router()
  authSerivce: AuthService

  constructor(defaultStrategy?: PassportStrategy) {
    this.authSerivce = new AuthService(defaultStrategy)
    this.initRoutes()
  }

  initRoutes(): void {
    this.router.get(
      "/:userID",
      this.authSerivce.isAuthorized(),
      this.authSerivce.hasPermission(this.name, "read"),
      param("userID").isNumeric(),
      this.authSerivce.validateRequest,
      this.controller.readUser
    )
  }
}
```

#### user.spec.ts

This is the test file for testing the component and its endpoints. You can read more about testing this architecture [here](/blog/nodejs-rest-api-testing/).

### Directory: src/api/middleware/

```
expressjs-api
└───src
    │
    └───api
        │
        └───middleware
            │   compression.ts
            │   loggin.ts
```

This folder includes all the API’s global middlewares like **compression**, request **logging** etc.

### File: src/api/routes.ts

```
expressjs-api
└───src
    │
    └───api
        │   routes.ts
```

Here we register all component and middleware routes. Those ones are used from the `server` class later on.

### File: src/api/server.ts

```
expressjs-api
└───src
    │
    └───api
       │   server.ts
```

Here we declare everything required for the Express.js server:

- import middlware
- import routes
- error handling

Later on, we can import the `server` class for unit tests as well.

### Directory: src/config

```
expressjs-api
└───src
    │
    └───config
       │   globals.ts
       │   logger.ts
       │   permissions.ts
```

This directory includes the API's configuration files. This could be for example:

- global variables
- logger config
- [ACL](https://www.npmjs.com/package/acl) permission
- SMTP config

Feel free to put any **config-related** files in here.

### Directory: src/services/

This directory contains global services we might need for **authorization**, sending **mails**, **caching**, or **helper** methods for example.

```
expressjs-api
└───src
    │
    └───services
        │   auth.ts
        │   helper.ts
        │   mail.ts
        |   redis.ts
```

#### auth.ts

Here we setup things like our app's passport strategies and define authorization methods.

#### helper.ts

The helper class contains helper methods for **hashing**, **UUIDs** and so on.

#### mail.ts

This service is used for sending **mails** and rendering the templates of the components. Again, I recommend the `renderFile` function of [ejs](https://www.npmjs.com/package/ejs).

### Directory: src/test/

This directory includes a test factory for running the component tests.
You can read more about it [here](/nodejs-rest-api-testing).

### File: src/app.ts

This is the startup file of our application. It initializes the database connection and starts the express server.

```
expressjs-api
└───src
    │   app.ts
```

### All together

Last but not least a complete overview of the project structure:

```
expressjs-api
└───src
    │
    └───config
    │   │   globals.ts
    │   │   logger.ts
    │   │   permissions.ts
    │
    └───api
    │   │
    │   └───components
    │   │   │
    │   │   └───article
    │   │   │
    │   │   └───user
    |   │   │   │
    |   │   │   └───templates
    |   │   │   |   │   confirmation.html
    |   │   │   |   │   invitation.html
    │   │   |   │   controller.ts
    │   │   |   │   model.ts
    │   │   |   │   policy.json
    │   │   |   │   repository.ts
    │   │   |   │   routes.ts
    │   │   |   │   user.spec.ts
    │   │
    │   └───middleware
    │   │   │   compression.ts
    │   │   │   logging.ts
    │   │
    │   │   routes.ts
    │   │   server.ts
    │
    └───services
    │
    └───test
    |
    │   app.ts
```

That’s it! I hope this is a little help for people who don't know how to structure their Node.js application or didn’t know how to start. I think there are still many things you can do better or in a more efficient way.

If you're interested in writing unit tests for Node.js REST APIs have a look at this [article](/nodejs-rest-api-testing) which covers the same architecture.

I also published a GitHub repository including an example application. [Have a look](https://github.com/larswaechter/expressjs-api).