Backend REST API & Controllers

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/public-api/index.ts
• packages/cli/src/public-api/v1/openapi.yml
• packages/cli/src/controllers/active-workflows.controller.ts
• CONTRIBUTING.md
• AGENTS.md

The n8n backend implements a REST API to manage workflows, credentials, and executions. This system follows a Controller-Service-Repository architectural pattern to decouple request handling from business logic and data persistence.

The API serves both the internal Vue.js frontend and external integrations through a public REST API. The core of this functionality resides in the packages/cli module, which contains the Express server, REST API definitions, and controller implementations.

Sources: CONTRIBUTING.md, AGENTS.md

Architectural Overview

The backend architecture uses Dependency Injection (DI) to manage components and enforce a clear separation of concerns. Controllers handle incoming HTTP requests, validate input, and delegate operations to domain-specific services.

The diagram shows the standard data flow where controllers act as the entry point for the business logic.
Sources: AGENTS.md, CONTRIBUTING.md

Key Components

Component	Responsibility
Express Router	Routes HTTP methods and paths to specific controller actions.
Controllers	Parse request parameters, handle authentication checks, and return HTTP responses.
Services	Contain the core business logic and coordinate between different modules.
Repositories	Manage database interactions using TypeORM.

Sources: AGENTS.md, CONTRIBUTING.md

Controller Implementation

Controllers in n8n are typically classes managed by the IoC container. They process data received from the client and return JSON responses or handle errors using specialized classes like UserError, OperationalError, or UnexpectedError.

Example: Active Workflows Controller

The ActiveWorkflowsController specifically manages the activation and deactivation states of workflows.

This sequence demonstrates how a controller facilitates a state change request.
Sources: packages/cli/src/controllers/active-workflows.controller.ts, AGENTS.md

Public REST API (v1)

n8n exposes a versioned public API (v1) defined via OpenAPI specifications. This API allows external systems to programmatically interact with the n8n instance.

API Entry Point

The public API is initialized through a central index that sets up versioned routes.

// packages/cli/src/public-api/index.ts
import { Router } from 'express';
// ... initialization logic

Sources: packages/cli/src/public-api/index.ts

Public API Endpoints

The following table summarizes common operations defined in the OpenAPI specification:

Endpoint	Method	Description
/workflows	GET	List all workflows.
/workflows/:id	GET	Retrieve details of a specific workflow.
/executions	GET	List workflow executions.
/credentials	GET	List available credentials.

Sources: packages/cli/src/public-api/v1/openapi.yml

Persistence and Data Flow

Business logic components must not import directly from @n8n/typeorm. Instead, they interact with the persistence layer through abstract repository methods. This ensures that the business logic remains independent of the specific database driver or ORM implementation.

The diagram illustrates the boundary between business logic and TypeORM entities.
Sources: AGENTS.md

Transaction Management

Transactions are orchestrated within the persistence layer using a TransactionRunner. Controllers and services pass an OperationContext to ensure that multiple repository calls participate in the same database transaction.

Sources: AGENTS.md

Development Patterns

When adding new API functionality, developers must:

1. Define Types: Add shared TypeScript interfaces to packages/@n8n/api-types.
2. Create Controllers: Implement the handler logic in packages/cli/src/controllers.
3. Update Routing: Register the new controller in the Express application.
4. Handle Errors: Use NodeApiError for API-related failures to ensure consistent error responses to the client.

Sources: AGENTS.md, CONTRIBUTING.md

Summary

The n8n Backend REST API and Controllers provide a structured interface for managing the automation engine. By utilizing a strict Controller-Service-Repository pattern and enforcing architectural boundaries—particularly around the persistence layer—the system maintains high modularity and testability. The inclusion of an OpenAPI-documented public API ensures that n8n remains extensible and integrable with third-party applications.