You Probably Don't Know How to Write APIs Like This Using Express

You Probably Don't Know How to Write APIs Like This Using Express Discovering a Different Approach in n8n When I first dove into the n8n codebase while working on LiveAPI, I expected the usual Express setup: a single routes file importing other modules, each API route calling a controller, passing through a validator, and ending up in a service file. This is the standard way most Node.js backends are structured, like in FlowiseAI or NodeBB. But n8n? It completely flipped my expectations. Instead of the usual route-controller-service flow, n8n takes a more TypeScript-heavy, decorator-driven approach that feels more like NestJS than traditional Express. It was a refreshing surprise, and I thought, "Okay, let's talk about this." So, let's break down how n8n structures its API in a way that’s both different and powerful, leveraging decorators, metadata, and dependency injection. The Server.ts File: A Custom Express Setup The heart of n8n’s backend lies in its Server class, which extends an AbstractServer and sets up an Express-based API. This isn’t just a simple Express app with some routes slapped onto it. Instead, it Dynamically loads controllers: Based on environment settings, controllers for authentication (LDAP, SAML), source control, MFA, and more are loaded at runtime. Handles webhooks & real-time events: WebSockets, Prometheus monitoring, and caching are integrated. Uses middleware: Helmet, CSP, cookie parsing, and rate limiting are configured dynamically. Handles SPA & frontend asset handling: Routes are served alongside API endpoints. But the real magic happens in how API routes are structured. The Decorators: A Different Way to Define APIs n8n ditches the typical routes folder and instead relies on TypeScript decorators for definning API endpoints. This is where it starts to feel very NestJS-like. Check out route.ts: No Traditional Route Files – Just Decorators Route decorators define API methods dynamically: import type { RequestHandler } from 'express'; import { getRouteMetadata } from './controller.registry'; import type { Controller, Method, RateLimit } from './types'; const RouteFactory = (method: Method) => (path: `/${string}`, options: RouteOptions = {}): MethodDecorator => (target, handlerName) => { const routeMetadata = getRouteMetadata(target.constructor as Controller, String(handlerName)); routeMetadata.method = method; routeMetadata.path = path; routeMetadata.middlewares = options.middlewares ?? []; }; export const Get = RouteFactory('get'); export const Post = RouteFactory('post'); export const Put = RouteFactory('put'); export const Patch = RouteFactory('patch'); export const Delete = RouteFactory('delete'); This approach eliminates the need for explicit route definitions. Instead, every controller method gets decorated with @Get(), @Post(), etc., and n8n handles the routing internally. The RestController Magic Instead of defining an Express router manually, the @RestController decorator registers an entire controller: import { Service } from '@n8n/di'; import { getControllerMetadata } from './controller.registry'; import type { Controller } from './types'; export const RestController = (basePath: `/${string}` = '/'): ClassDecorator => (target) => { const metadata = getControllerMetadata(target as unknown as Controller); metadata.basePath = basePath; return Service()(target); }; This automatically registers the controller and maps its routes. Example: Active Workflows API The ActiveWorkflowsController (source) handles workflow-related API endpoints. import { Get, RestController } from '@/decorators'; import { ActiveWorkflowRequest } from '@/requests'; import { ActiveWorkflowsService } from '@/services/active-workflows.service'; @RestController('/active-workflows') export class ActiveWorkflowsController { constructor(private readonly activeWorkflowsService: ActiveWorkflowsService) {} @Get('/') async getActiveWorkflows(req: ActiveWorkflowRequest.GetAllActive) { return await this.activeWorkflowsService.getAllActiveIdsFor(req.user); } @Get('/error/:id') async getActivationError(req: ActiveWorkflowRequest.GetActivationError) { const { user, params: { id: workflowId } } = req; return await this.activeWorkflowsService.getActivationError(workflowId, user); } } Each API method is just a function inside a class, and decorators handle everything—route mapping, authentication, validation, and more. Service Layer: Dependency Injection & Database Access n8n uses dependency injection (@n8n/di) to manage its services. The ActiveWorkflowsService handles workflow-related operations: @Service() export class ActiveWorkflowsService { constructor( private readonly logger: Logger, private readon

import type { RequestHandler } from 'express';

import { getRouteMetadata } from './controller.registry';
import type { Controller, Method, RateLimit } from './types';

const RouteFactory =
    (method: Method) =>
    (path: `/${string}`, options: RouteOptions = {}): MethodDecorator =>
    (target, handlerName) => {
        const routeMetadata = getRouteMetadata(target.constructor as Controller, String(handlerName));
        routeMetadata.method = method;
        routeMetadata.path = path;
        routeMetadata.middlewares = options.middlewares ?? [];
    };

export const Get = RouteFactory('get');
export const Post = RouteFactory('post');
export const Put = RouteFactory('put');
export const Patch = RouteFactory('patch');
export const Delete = RouteFactory('delete');

import { Service } from '@n8n/di';

import { getControllerMetadata } from './controller.registry';
import type { Controller } from './types';

export const RestController =
    (basePath: `/${string}` = '/'): ClassDecorator =>
    (target) => {
        const metadata = getControllerMetadata(target as unknown as Controller);
        metadata.basePath = basePath;
        return Service()(target);
    };

import { Get, RestController } from '@/decorators';
import { ActiveWorkflowRequest } from '@/requests';
import { ActiveWorkflowsService } from '@/services/active-workflows.service';

@RestController('/active-workflows')
export class ActiveWorkflowsController {
    constructor(private readonly activeWorkflowsService: ActiveWorkflowsService) {}

    @Get('/')
    async getActiveWorkflows(req: ActiveWorkflowRequest.GetAllActive) {
        return await this.activeWorkflowsService.getAllActiveIdsFor(req.user);
    }

    @Get('/error/:id')
    async getActivationError(req: ActiveWorkflowRequest.GetActivationError) {
        const { user, params: { id: workflowId } } = req;
        return await this.activeWorkflowsService.getActivationError(workflowId, user);
    }
}

@Service()
export class ActiveWorkflowsService {
    constructor(
        private readonly logger: Logger,
        private readonly workflowRepository: WorkflowRepository,
        private readonly sharedWorkflowRepository: SharedWorkflowRepository,
        private readonly activationErrorsService: ActivationErrorsService,
    ) {}

    async getAllActiveIdsFor(user: User) {
        const activationErrors = await this.activationErrorsService.getAll();
        const activeWorkflowIds = await this.workflowRepository.getActiveIds();

        const hasFullAccess = user.hasGlobalScope('workflow:list');
        if (hasFullAccess) {
            return activeWorkflowIds.filter((workflowId) => !activationErrors[workflowId]);
        }

        const sharedWorkflowIds =
            await this.sharedWorkflowRepository.getSharedWorkflowIds(activeWorkflowIds);
        return sharedWorkflowIds.filter((workflowId) => !activationErrors[workflowId]);
    }
}

Related Posts

Redis Essentials: Common Data Types and Best Practices

Mar 13, 2025  0

Is CQRS CQRS without separate read and write data stores?

Feb 2, 2025  0

8 Golden Rules of Interface Design & Best Practices

Mar 26, 2025  0