REST API

Relevant source files

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

• packages/cli/src/modules/instance-ai/eval/mock-handler.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts
• packages/quality/testing/janitor/src/rules/api-purity.rule.test.ts
• packages/nodes-base/nodes/Webhook/Webhook.node.json
• CONTRIBUTING.md

The n8n REST API provides a programmatic interface for interacting with the n8n application. It enables developers to manage workflows, credentials, and executions externally. The system includes core modules for handling HTTP requests, a mock handler for testing, and specialized nodes for creating custom API endpoints within workflows.

Sources: packages/cli/src/modules/instance-ai/eval/mock-handler.ts:13-19, CONTRIBUTING.md:40-42

API Architecture and Core Modules

The n8n backend implements REST API logic primarily within the packages/cli module. This module contains the code for n8n's public APIs and manages communication between the frontend editor and the backend server. The application uses a mono-repository structure where the CLI handles both the API execution and the management of workflow assets.

Sources: CONTRIBUTING.md:40-42

HTTP Request Handling

The system processes HTTP requests through dedicated nodes and internal handlers. The HTTP Request node (n8n-nodes-base.httpRequest) serves as the primary tool for fetching data from external REST APIs. It supports various authentication methods, pagination for large datasets, and the ability to import cURL commands for complex requests.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts:46-56

Webhook and API Endpoints

n8n allows users to build custom REST API endpoints using the Webhook node. This node acts as a trigger that starts a workflow when an external system sends an HTTP request to a specific URL.

Webhook Node Configuration

The Webhook node supports various HTTP methods and response modes. Developers can configure how the API responds to incoming requests, including returning immediate status codes or waiting for workflow completion to return processed data.

Sources: packages/nodes-base/nodes/Webhook/Webhook.node.json:1-10, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts:24-30

Feature	Description
HTTP Methods	Supports GET, POST, PUT, PATCH, DELETE
Response Modes	Immediate response or response via 'Respond to Webhook' node
Authentication	Basic Auth, Header Auth, or No Auth options
Content Types	JSON, Form Data, Raw Text, Binary

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/web-app.ts:58-65

Mocking and Evaluation

For testing and evaluation purposes, n8n implements an LLM-powered HTTP mock handler. This system generates realistic HTTP responses for API requests during workflow evaluation, allowing for self-validation without hitting real external endpoints.

Mock Handler Logic

The mock handler sanitizes request bodies to remove sensitive data before processing. It uses API documentation and node configurations to ensure the generated response matches the expected schema of the target service.

Sources: packages/cli/src/modules/instance-ai/eval/mock-handler.ts:13-25, packages/cli/src/modules/instance-ai/eval/mock-handler.ts:41-55

Development and Testing

The project maintains strict rules for internal API usage during development. Developers are encouraged to use higher-level API services rather than raw fetch or request calls in tests to maintain "API Purity."

API Purity Rules

A specialized "Janitor" rule (ApiPurityRule) detects and flags direct usage of raw HTTP clients in the codebase. It suggests using the structured api helper instead.

Sources: packages/quality/testing/janitor/src/rules/api-purity.rule.test.ts:9-25

// Correct usage: using the API service
test('creates workflow', async ({ n8n, api }) => {
    await api.workflows.create({ name: 'Test' });
});

// Violation: using raw request object
test('gets workflow', async ({ request }) => {
    const response = await request.get('/api/workflows');
});

Sources: packages/quality/testing/janitor/src/rules/api-purity.rule.test.ts:12-32

Summary

The n8n REST API system is a multi-faceted architecture that manages internal application state and enables the creation of custom external endpoints. By utilizing the packages/cli core modules for public exposure and the Webhook and HTTP Request nodes for workflow integration, n8n provides a robust environment for programmatic automation. Testing is supported through an advanced LLM mock handler that ensures integration reliability without external dependencies.