Маршруты и WAF

Управление маршрутами через REST API: маршрутизация HTTP-трафика по путям к сервисам проекта или внешним upstream. Маршруты поддерживают WAF (ModSecurity, rate limiting, базовая аутентификация, IP-правила). Все методы требуют токен аутентификации.

POST /v1/project/:projectId/route

Создаёт в указанном проекте маршрут, направляющий HTTP-трафик по пути path к сервису проекта (internal) или внешнему upstream (external); тип по умолчанию — internal. Маршрут привязывается к домену через domainId, а для типа internal дополнительно указываются serviceId и порт сервиса. Ответ содержит объект RouteResponse: новый маршрут создаётся со статусом creating.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`projectId`	Path	UUID	Да	ID проекта

Body:

Параметр	Тип	Обязательный	Описание
`name`	string	Да	Имя маршрута (латиница в нижнем регистре, цифры, дефис и точка)
`domainId`	string	Да	ID домена
`serviceId`	string	Нет	ID сервиса (для internal)
`port`	string	Нет	Порт сервиса
`path`	string	Да	Путь маршрутизации
`type`	string	Нет	Тип маршрута (`internal` или `external`, по умолчанию `internal`)
`upstream`	string	Нет	URL upstream (для external)
`rewrites`	array	Нет	Rewrite правила (максимум 20)

Пример запроса:

{
    "name": "api-route",
    "domainId": "660e8400-e29b-41d4-a716-446655440010",
    "serviceId": "880e8400-e29b-41d4-a716-446655440003",
    "port": "8080/tcp",
    "path": "/api",
    "type": "internal",
    "rewrites": [
        {
            "path": "/v1(/.*)?",
            "target": "/v2$1",
            "mode": "redirect"
        }
    ]
}

Ответ:

{
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "name": "api-route",
    "path": "/api",
    "port": "8080/TCP",
    "status": "creating",
    "type": "internal",
    "createdAt": "2024-01-15T10:30:00+00:00",
    "updatedAt": "2024-01-15T10:30:00+00:00",
    "rewrites": [
        {
            "path": "/v1(/.*)?",
            "target": "/v2$1",
            "mode": "redirect"
        }
    ]
}

Ошибки:

404 Not Found — Проект не найден
400 Bad Request — Невалидные параметры

PUT /v1/route/:routeId

Обновляет существующий маршрут по его UUID. Принимает те же параметры, что и создание, — включая путь маршрутизации, тип маршрута, привязку к домену, сервису, upstream и rewrite правила. Возвращает обновлённый объект RouteResponse.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`routeId`	Path	UUID	Да	ID маршрута

Body:

Параметр	Тип	Обязательный	Описание
`domainId`	string	Да	ID домена
`serviceId`	string	Нет	ID сервиса (для internal)
`port`	string	Нет	Порт сервиса
`path`	string	Да	Путь маршрутизации
`type`	string	Нет	Тип маршрута (`internal` или `external`, по умолчанию `internal`)
`upstream`	string	Нет	URL upstream (для external)
`rewrites`	array	Нет	Rewrite правила (максимум 20)

Пример запроса:

{
    "domainId": "660e8400-e29b-41d4-a716-446655440010",
    "serviceId": "880e8400-e29b-41d4-a716-446655440003",
    "port": "8080/tcp",
    "path": "/api/v2",
    "type": "internal",
    "rewrites": [
        {
            "path": "/v1(/.*)?",
            "target": "/v2$1",
            "mode": "redirect"
        }
    ]
}

Ответ:

{
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "name": "api-route",
    "path": "/api/v2",
    "port": "8080/TCP",
    "status": "ready",
    "type": "internal",
    "createdAt": "2024-01-15T10:30:00+00:00",
    "updatedAt": "2024-01-15T11:45:00+00:00",
    "rewrites": [
        {
            "path": "/v1(/.*)?",
            "target": "/v2$1",
            "mode": "redirect"
        }
    ]
}

Ошибки:

404 Not Found — Маршрут не найден

GET /v1/route/:routeId

Возвращает один маршрут по его UUID. Ответ — объект RouteResponse, включающий имя, путь маршрутизации, порт, статус, тип маршрута (internal или external), rewrite правила и даты создания и обновления.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`routeId`	Path	UUID	Да	ID маршрута

Ответ:

{
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "name": "api-route",
    "path": "/api",
    "port": "8080/TCP",
    "status": "ready",
    "type": "internal",
    "createdAt": "2024-01-15T10:30:00+00:00",
    "updatedAt": "2024-01-15T10:30:00+00:00",
    "rewrites": [
        {
            "path": "/v1(/.*)?",
            "target": "/v2$1",
            "mode": "redirect"
        }
    ]
}

Ошибки:

404 Not Found — Маршрут не найден

GET /v1/project/:projectId/routes

Возвращает все маршруты, созданные в указанном проекте. Ответ содержит массив объектов RouteResponse с тем же набором полей, что и при получении одного маршрута.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`projectId`	Path	UUID	Да	ID проекта

Ответ:

[
    {
        "id": "990e8400-e29b-41d4-a716-446655440004",
        "name": "api-route",
        "path": "/api",
        "port": "8080/TCP",
        "status": "ready",
        "type": "internal",
        "createdAt": "2024-01-15T10:30:00+00:00",
        "updatedAt": "2024-01-15T10:30:00+00:00",
        "rewrites": [
            {
                "path": "/v1(/.*)?",
                "target": "/v2$1",
                "mode": "redirect"
            }
        ]
    }
]

Ошибки:

404 Not Found — Проект не найден

GET /v1/domain/:domainId/routes

Возвращает все маршруты, привязанные к указанному домену через domainId. Ответ содержит массив объектов RouteResponse — по структуре он совпадает со списком маршрутов проекта.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`domainId`	Path	UUID	Да	ID домена

Ответ:

[
    {
        "id": "990e8400-e29b-41d4-a716-446655440004",
        "name": "api-route",
        "path": "/api",
        "port": "8080/TCP",
        "status": "ready",
        "type": "internal",
        "createdAt": "2024-01-15T10:30:00+00:00",
        "updatedAt": "2024-01-15T10:30:00+00:00",
        "rewrites": [
            {
                "path": "/v1(/.*)?",
                "target": "/v2$1",
                "mode": "redirect"
            }
        ]
    }
]

Ошибки:

404 Not Found — Домен не найден

POST /v1/route/:routeId/reload

Перезагружает конфигурацию маршрута, повторно применяя текущие настройки маршрутизации HTTP-трафика. Возвращает объект RouteResponse.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`routeId`	Path	UUID	Да	ID маршрута

Ответ:

{
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "name": "api-route",
    "path": "/api",
    "port": "8080/TCP",
    "status": "ready",
    "type": "internal",
    "createdAt": "2024-01-15T10:30:00+00:00",
    "updatedAt": "2024-01-15T10:30:00+00:00",
    "rewrites": [
        {
            "path": "/v1(/.*)?",
            "target": "/v2$1",
            "mode": "redirect"
        }
    ]
}

Ошибки:

404 Not Found — Маршрут не найден

DELETE /v1/route/:routeId

Удаляет маршрут по его UUID. При успешном удалении метод возвращает пустой ответ без тела.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`routeId`	Path	UUID	Да	ID маршрута

Ответ: 204 No Content — пустой ответ при успешном удалении.

Ошибки:

404 Not Found — Маршрут не найден

GET /v1/route/:routeId/waf

Возвращает WAF-конфигурацию маршрута. Ответ включает настройки ModSecurity (modSecurityEnable, modSecurityLevel), параметры rate limiting (rateLimitTotal, rateLimitBurst), правила IP-фильтрации ipRules и данные базовой аутентификации (authUsername, authPassword).

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`routeId`	Path	UUID	Да	ID маршрута

Ответ:

{
    "id": "ee0e8400-e29b-41d4-a716-446655440005",
    "modSecurityEnable": true,
    "modSecurityLevel": 2,
    "rateLimitEnable": true,
    "rateLimitTotal": 1000,
    "rateLimitBurst": 100,
    "ipRules": [
        {
            "ip": "192.168.1.1",
            "action": "allow"
        }
    ],
    "authEnable": true,
    "authUsername": "admin",
    "authPassword": "secret"
}

Ошибки:

404 Not Found — Маршрут не найден

PUT /v1/route/:routeId/waf

Обновляет WAF-конфигурацию маршрута: параметры ModSecurity, rate limiting, правила IP-фильтрации и базовой аутентификации. Тело запроса принимает те же секции настроек, что возвращает GET-метод WAF, — от уровня modSecurityLevel до списка ipRules. Возвращает объект RouteWafResponse.

Параметры:

Параметр	Место	Тип	Обязательный	Описание
`routeId`	Path	UUID	Да	ID маршрута

Пример запроса:

{
    "modSecurityEnable": true,
    "modSecurityLevel": 2,
    "rateLimitEnable": true,
    "rateLimitTotal": 1000,
    "rateLimitBurst": 100,
    "ipRules": [
        {
            "ip": "192.168.1.1",
            "action": "allow"
        }
    ],
    "authEnable": true,
    "authUsername": "admin",
    "authPassword": "secret"
}

Ответ:

{
    "id": "ee0e8400-e29b-41d4-a716-446655440005",
    "modSecurityEnable": true,
    "modSecurityLevel": 2,
    "rateLimitEnable": true,
    "rateLimitTotal": 1000,
    "rateLimitBurst": 100,
    "ipRules": [
        {
            "ip": "192.168.1.1",
            "action": "allow"
        }
    ],
    "authEnable": true,
    "authUsername": "admin",
    "authPassword": "secret"
}

Ошибки:

404 Not Found — Маршрут не найден

Структура rewrite правил

Rewrite правила позволяют перенаправлять или переписывать URL внутри маршрута. Каждое правило содержит три поля:

Поле	Тип	Описание
`path`	string	Regex паттерн для матчинга URI (относительный путь от `route.path`)
`target`	string	Целевой путь (поддерживает capture groups: `$1`, `$2`, и т.д.)
`mode`	string	Режим: `redirect` (внешний редирект 302) или `rewrite` (внутренний)

Режимы работы:

redirect — внешний редирект (HTTP 302). URL в браузере меняется.
rewrite — внутренний rewrite. URL в браузере НЕ меняется, запрос проксируется с измененным URI.

Пример:

{
    "path": "/v1(/.*)?",
    "target": "/v2$1",
    "mode": "redirect"
}

Этот пример перенаправляет /api/v1/users на /v2/users (302 redirect).

Максимальное количество rewrite правил в одном маршруте — 20.

Маршруты и WAF

POST /v1/project/:projectId/route

PUT /v1/route/:routeId

GET /v1/route/:routeId

GET /v1/project/:projectId/routes

GET /v1/domain/:domainId/routes

POST /v1/route/:routeId/reload

DELETE /v1/route/:routeId

GET /v1/route/:routeId/waf

PUT /v1/route/:routeId/waf

Структура rewrite правил

Мы используем файлы cookies