# 01-OVERVIEW.md - n8n REST API Overview

**Версия API:** v1
**Дата документации:** 2025-12-25
**Источник:** Официальная документация n8n через Context7

---

## 📋 Содержание

1. [Введение](#введение)
2. [Что такое n8n REST API](#что-такое-n8n-rest-api)
3. [Возможности API](#возможности-api)
4. [Архитектура API](#архитектура-api)
5. [Base URLs](#base-urls)
6. [Версионирование](#версионирование)
7. [Форматы данных](#форматы-данных)
8. [Основные концепции](#основные-концепции)
9. [Начало работы](#начало-работы)
10. [Ограничения](#ограничения)

---

## Введение

n8n REST API предоставляет программный доступ к функциям n8n automation platform. API позволяет создавать, управлять и мониторить workflows, executions, credentials и tags через HTTP запросы, обеспечивая интеграцию n8n в ваши системы и процессы.

---

## Что такое n8n REST API

### Определение

n8n REST API - это RESTful HTTP API, который позволяет программно выполнять многие из тех же задач, что и в графическом интерфейсе (GUI) n8n. API следует принципам REST архитектуры и использует стандартные HTTP методы для взаимодействия с ресурсами.

### Основные принципы REST

**n8n REST API следует стандартным REST принципам:**

1. **Resource-Based** - Все операции выполняются над ресурсами (workflows, executions, credentials, tags)
2. **HTTP Methods** - Стандартные HTTP методы определяют действия:
   - `GET` - Получить ресурс(ы)
   - `POST` - Создать новый ресурс
   - `PUT` - Полностью обновить ресурс
   - `PATCH` - Частично обновить ресурс
   - `DELETE` - Удалить ресурс

3. **Stateless** - Каждый запрос содержит всю необходимую информацию для обработки
4. **JSON Format** - Все данные передаются в формате JSON
5. **HTTP Status Codes** - Стандартные коды ответов указывают на результат операции

---

## Возможности API

n8n REST API предоставляет следующие категории функциональности:

### 1. Workflows Management (Управление рабочими процессами)

**Основные операции:**
- ✅ Создание новых workflows программно
- ✅ Получение списка workflows с фильтрацией
- ✅ Получение детальной информации о workflow
- ✅ Обновление существующих workflows (полное и частичное)
- ✅ Удаление workflows
- ✅ Активация и деактивация workflows
- ✅ Клонирование и экспорт workflows

**Подробнее:** [10-WORKFLOWS-API.md](./10-WORKFLOWS-API.md)

### 2. Executions Monitoring (Мониторинг выполнений)

**Основные операции:**
- ✅ Просмотр истории выполнений workflows
- ✅ Получение детальной информации о execution
- ✅ Фильтрация executions по статусу, workflow, дате
- ✅ Повторное выполнение (retry) failed executions
- ✅ Удаление executions из истории

**Подробнее:** [20-EXECUTIONS-API.md](./20-EXECUTIONS-API.md)

### 3. Credentials Management (Управление учетными данными)

**Основные операции:**
- ✅ Создание credentials для внешних сервисов
- ✅ Получение списка credentials
- ✅ Обновление существующих credentials
- ✅ Удаление credentials
- ✅ Управление доступом к credentials

**Подробнее:** [30-CREDENTIALS-API.md](./30-CREDENTIALS-API.md)

**Примечание:** Credentials API описан согласно официальной документации, но не реализован в MCP сервере n8n-workflow-builder.

### 4. Tags Organization (Организация через теги)

**Основные операции:**
- ✅ Создание tags для классификации workflows
- ✅ Получение списка tags
- ✅ Обновление tags
- ✅ Удаление tags
- ✅ Назначение tags workflows

**Подробнее:** [40-TAGS-API.md](./40-TAGS-API.md)

---

## Архитектура API

### RESTful Структура

n8n REST API построен на основе RESTful архитектуры:

```
/api/v1/
├── workflows/          # Управление workflows
│   ├── GET /workflows
│   ├── POST /workflows
│   ├── GET /workflows/{id}
│   ├── PUT /workflows/{id}
│   ├── PATCH /workflows/{id}
│   ├── DELETE /workflows/{id}
│   ├── PUT /workflows/{id}/activate
│   └── PUT /workflows/{id}/deactivate
│
├── executions/         # Мониторинг executions
│   ├── GET /executions
│   ├── GET /executions/{id}
│   ├── DELETE /executions/{id}
│   └── POST /executions/{id}/retry
│
├── credentials/        # Управление credentials
│   ├── GET /credentials
│   ├── POST /credentials
│   ├── GET /credentials/{id}
│   ├── PUT /credentials/{id}
│   ├── DELETE /credentials/{id}
│   └── GET /credentials/schema/{typeName}
│
└── tags/              # Организация через tags
    ├── GET /tags
    ├── POST /tags
    ├── GET /tags/{id}
    ├── PUT /tags/{id}
    └── DELETE /tags/{id}
```

### Компоненты Архитектуры

**1. HTTP Layer**
- Стандартные HTTP методы (GET, POST, PUT, PATCH, DELETE)
- HTTP заголовки для аутентификации и content negotiation
- HTTP status codes для индикации результата

**2. Authentication Layer**
- API key authentication через header `X-N8N-API-KEY`
- Безопасная передача credentials через HTTPS

**3. Data Layer**
- JSON формат для всех запросов и ответов
- Валидация входных данных
- Трансформация данных между форматами

**4. Business Logic Layer**
- Обработка workflows, executions, credentials, tags
- Валидация бизнес-правил
- Управление состоянием ресурсов

---

## Base URLs

### n8n Cloud

Для n8n Cloud instances используйте следующий формат:

```
https://{instance}.app.n8n.cloud/api/v1
```

**Где:**
- `{instance}` - название вашего n8n Cloud instance

**Примеры:**
```
https://my-company.app.n8n.cloud/api/v1
https://production-n8n.app.n8n.cloud/api/v1
```

### Self-Hosted

Для self-hosted n8n installations используйте:

```
{url}/api/v1
```

**Где:**
- `{url}` - URL вашего self-hosted n8n сервера

**Примеры:**
```
https://n8n.example.com/api/v1
http://localhost:5678/api/v1
https://automation.company.com/api/v1
```

### Полные URL примеры

**Cloud Instance:**
```bash
# Список workflows
GET https://my-company.app.n8n.cloud/api/v1/workflows

# Создать workflow
POST https://my-company.app.n8n.cloud/api/v1/workflows

# Получить execution
GET https://my-company.app.n8n.cloud/api/v1/executions/123
```

**Self-Hosted:**
```bash
# Список workflows
GET https://n8n.example.com/api/v1/workflows

# Создать tag
POST https://n8n.example.com/api/v1/tags

# Активировать workflow
PUT https://n8n.example.com/api/v1/workflows/456/activate
```

---

## Версионирование

### Текущая версия: v1

n8n REST API использует версионирование в URL path:

```
/api/v1/{resource}
```

**Стабильность:**
- API v1 является стабильной версией
- Обратная совместимость поддерживается в рамках одной major version
- Изменения, ломающие совместимость, будут введены в новой major version (v2)

**Best Practices:**
- Всегда указывайте версию API в запросах
- Мониторьте официальные changelog для изменений API
- Тестируйте интеграции при обновлении n8n

---

## Форматы данных

### Request Format

**Content-Type:** `application/json`

Все POST, PUT, PATCH запросы должны отправлять данные в JSON формате:

```http
POST /api/v1/workflows HTTP/1.1
Host: n8n.example.com
Content-Type: application/json
X-N8N-API-KEY: your_api_key_here

{
  "name": "My Workflow",
  "nodes": [...],
  "connections": {...}
}
```

### Response Format

**Content-Type:** `application/json`

Все ответы возвращаются в JSON формате:

```json
{
  "id": "123",
  "name": "My Workflow",
  "active": true,
  "createdAt": "2025-12-25T10:00:00.000Z",
  "updatedAt": "2025-12-25T10:00:00.000Z"
}
```

### Common Response Structures

**Single Resource Response:**
```json
{
  "id": "123",
  "name": "Resource Name",
  ...other fields
}
```

**List Response (with pagination):**
```json
{
  "data": [
    {
      "id": "123",
      "name": "Item 1"
    },
    {
      "id": "456",
      "name": "Item 2"
    }
  ],
  "nextCursor": "cursor_token_here"
}
```

**Error Response:**
```json
{
  "error": "Error message describing what went wrong"
}
```

---

## Основные концепции

### 1. Resources (Ресурсы)

n8n API работает со следующими основными ресурсами:

**Workflow**
- Определение automation workflow
- Содержит nodes (узлы) и connections (связи)
- Может быть активным или неактивным

**Execution**
- Запись о выполнении workflow
- Содержит результаты, ошибки, timing информацию
- Может иметь статусы: success, error, waiting

**Credential**
- Учетные данные для аутентификации с внешними сервисами
- Безопасно зашифрованы в n8n
- Используются nodes в workflows

**Tag**
- Метка для организации workflows
- Помогает категоризировать и фильтровать workflows

### 2. HTTP Methods Семантика

**GET** - Получить ресурс(ы)
- Безопасный (не изменяет данные)
- Идемпотентный (повторные запросы дают тот же результат)
- Поддерживает фильтрацию через query parameters

**POST** - Создать новый ресурс
- Не идемпотентный (каждый запрос создает новый ресурс)
- Возвращает созданный ресурс с ID

**PUT** - Полностью заменить ресурс
- Идемпотентный
- Требует полное представление ресурса

**PATCH** - Частично обновить ресурс
- Может быть идемпотентным
- Обновляет только указанные поля

**DELETE** - Удалить ресурс
- Идемпотентный
- Обычно возвращает 204 No Content

### 3. Status Codes

n8n API использует стандартные HTTP status codes:

**2xx Success:**
- `200 OK` - Успешный GET, PUT, PATCH
- `201 Created` - Успешный POST
- `204 No Content` - Успешный DELETE

**4xx Client Errors:**
- `400 Bad Request` - Неверные данные запроса
- `401 Unauthorized` - Отсутствует или неверный API key
- `404 Not Found` - Ресурс не найден
- `409 Conflict` - Конфликт (например, дубликат)

**5xx Server Errors:**
- `500 Internal Server Error` - Внутренняя ошибка сервера

### 4. Pagination

Для endpoints, возвращающих списки, используется cursor-based pagination:

**Request:**
```bash
GET /api/v1/workflows?limit=100&cursor=cursor_token
```

**Response:**
```json
{
  "data": [...],
  "nextCursor": "next_cursor_token"
}
```

**Подробнее:** [03-PAGINATION.md](./03-PAGINATION.md)

### 5. Authentication

Все API запросы требуют аутентификации через API key:

```http
GET /api/v1/workflows HTTP/1.1
Host: n8n.example.com
X-N8N-API-KEY: your_api_key_here
Accept: application/json
```

**Подробнее:** [02-AUTHENTICATION.md](./02-AUTHENTICATION.md)

---

## Начало работы

### Шаг 1: Получить API Key

**n8n Cloud:**
1. Войдите в свой n8n Cloud instance
2. Перейдите в Settings → API
3. Создайте новый API key
4. Сохраните key в безопасном месте

**Self-Hosted:**
1. Войдите в свой n8n instance
2. Перейдите в Settings → API
3. Создайте новый API key
4. Сохраните key в безопасном месте

### Шаг 2: Первый API запрос

**Тест подключения - получить список workflows:**

```bash
curl -X GET \
  'https://your-instance.app.n8n.cloud/api/v1/workflows' \
  -H 'X-N8N-API-KEY: your_api_key_here' \
  -H 'Accept: application/json'
```

**Ожидаемый результат:**
```json
{
  "data": [
    {
      "id": "123",
      "name": "My First Workflow",
      "active": true,
      "createdAt": "2025-12-20T10:00:00.000Z",
      "updatedAt": "2025-12-20T10:00:00.000Z"
    }
  ]
}
```

### Шаг 3: Создать простой workflow

```bash
curl -X POST \
  'https://your-instance.app.n8n.cloud/api/v1/workflows' \
  -H 'X-N8N-API-KEY: your_api_key_here' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "name": "API Test Workflow",
    "nodes": [
      {
        "name": "Start",
        "type": "n8n-nodes-base.start",
        "typeVersion": 1,
        "position": [250, 300],
        "parameters": {}
      }
    ],
    "connections": {},
    "active": false,
    "settings": {}
  }'
```

### Шаг 4: Изучить документацию endpoints

- [Workflows API](./10-WORKFLOWS-API.md) - Полное управление workflows
- [Executions API](./20-EXECUTIONS-API.md) - Мониторинг выполнений
- [Credentials API](./30-CREDENTIALS-API.md) - Управление credentials
- [Tags API](./40-TAGS-API.md) - Организация workflows

---

## Ограничения

### Rate Limiting

**n8n Cloud:**
- Rate limiting применяется для защиты инфраструктуры
- Конкретные лимиты зависят от вашего плана
- При превышении лимита возвращается `429 Too Many Requests`

**Self-Hosted:**
- Rate limiting можно настроить через environment variables
- По умолчанию лимиты отсутствуют

### Размер данных

**Request Body Size:**
- Максимальный размер request body зависит от конфигурации сервера
- Рекомендуется держать workflows в разумных размерах

**Response Size:**
- Большие workflows могут возвращать значительные объемы данных
- Используйте pagination для списков

### Concurrent Operations

**Workflow Execution:**
- Количество одновременных executions ограничено настройками instance
- Cloud plans имеют различные лимиты по concurrency

### Deprecated Features

**Следите за changelog для:**
- Устаревших endpoints
- Изменений в структуре данных
- Новых версий API

---

## Дополнительные ресурсы

### Официальная документация

- [n8n REST API Documentation](https://docs.n8n.io/api/)
- [n8n REST API Reference](https://docs.n8n.io/api/api-reference/)

### Полезные ссылки

- **Основы REST APIs:**
  - [KnowledgeOwl's guide to working with APIs](https://support.knowledgeowl.com/help/working-with-apis)
  - [IBM Cloud - What is an API](https://www.ibm.com/cloud/learn/api)
  - [IBM Cloud - What is a REST API?](https://www.ibm.com/cloud/learn/rest-apis)
  - [MDN - An overview of HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview)

### Community & Support

- [n8n Community Forum](https://community.n8n.io/)
- [n8n GitHub Repository](https://github.com/n8n-io/n8n)
- [n8n Documentation](https://docs.n8n.io/)

---

## Примеры использования

### JavaScript/Node.js пример

```javascript
const axios = require('axios');

const N8N_API_KEY = 'your_api_key_here';
const N8N_HOST = 'https://your-instance.app.n8n.cloud';

async function listWorkflows() {
  try {
    const response = await axios.get(`${N8N_HOST}/api/v1/workflows`, {
      headers: {
        'X-N8N-API-KEY': N8N_API_KEY,
        'Accept': 'application/json'
      }
    });

    console.log('Workflows:', response.data.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}

listWorkflows();
```

### Python пример

```python
import requests

N8N_API_KEY = 'your_api_key_here'
N8N_HOST = 'https://your-instance.app.n8n.cloud'

def list_workflows():
    try:
        response = requests.get(
            f'{N8N_HOST}/api/v1/workflows',
            headers={
                'X-N8N-API-KEY': N8N_API_KEY,
                'Accept': 'application/json'
            }
        )
        response.raise_for_status()

        print('Workflows:', response.json()['data'])
        return response.json()
    except requests.exceptions.RequestException as error:
        print('Error:', error)
        raise

list_workflows()
```

---

## Следующие шаги

1. **Настройте аутентификацию:** Прочитайте [02-AUTHENTICATION.md](./02-AUTHENTICATION.md)
2. **Изучите пагинацию:** Прочитайте [03-PAGINATION.md](./03-PAGINATION.md)
3. **Начните с Workflows API:** Прочитайте [10-WORKFLOWS-API.md](./10-WORKFLOWS-API.md)

---

**Последнее обновление:** 2025-12-25
**Версия документации:** 1.0
**Подготовлено:** James (Dev Agent) с использованием Context7 MCP Server

**Источники:**
- [n8n REST API Documentation](https://docs.n8n.io/api/)
- [n8n API Reference](https://docs.n8n.io/api/api-reference/)