REST

1. Роль протокола в проекте

REST - базовый и первый по очередности реализации протокол платформы. На нем должна быть обкатана общая модель Operation, схема входа и выхода, маппинг, тестовый запуск и публикация MCP tool.

2. Что поддерживается в целевом продукте

HTTP methods: GET, POST, PUT, PATCH, DELETE
загрузка примера входного JSON
загрузка примера выходного JSON
path parameters
query parameters
headers
JSON request body
JSON response body
auth: Bearer, Basic, API key
timeout и базовые transport settings
request mapping
response mapping
автогенерация чернового mapping
ручная донастройка через JSONPath
тестовый вызов перед публикацией
optional REST SSE upstream в bounded window и session режимах

3. Что отложено

multipart/form-data
file upload/download как отдельный сценарий
XML payload как основной формат
OpenAPI import с автоматическим созданием mappings
webhooks
long polling как специальный режим
HEAD и OPTIONS как отдельные пользовательские сценарии
raw infinite SSE passthrough

4. Внутренняя модель REST operation

REST operation в системе описывается следующими основными частями:

base_url
method
path_template
headers
auth_profile
input_schema
input_mapping
output_schema
output_mapping
tool_description

На слое MCP REST operation всегда выглядит как вызов запрос -> ответ с фиксированной схемой входа и выхода.

Если upstream использует SSE, на слое MCP это все равно должно быть выражено как:

bounded window result;
session-oriented start/poll/stop;
async job semantics для длительных действий.

5. Как оператор настраивает REST operation

Указывает base_url.
Выбирает HTTP method.
Указывает path_template.
При необходимости загружает пример входного и выходного JSON.
Система строит черновую схему и стартовый mapping.
Описывает или уточняет входные MCP-параметры.
Сопоставляет параметры с path, query, headers и body.
Указывает, откуда извлекать полезные данные в ответе.
При необходимости уточняет mapping через JSONPath.
Запускает тест.
Публикует operation как MCP tool.

6. Требования к маппингу

Input mapping должен поддерживать:

$.mcp.* -> $.request.path.*
$.mcp.* -> $.request.query.*
$.mcp.* -> $.request.headers.*
$.mcp.* -> $.request.body.*
константы
значения по умолчанию

Output mapping должен поддерживать:

$.response.body.* -> $.output.*
извлечение вложенных полей
нормализацию отсутствующих значений

JSONPath является основным способом адресации конкретных параметров при работе со вложенными объектами и массивами.

7. Поведение runtime

При выполнении REST operation runtime должен:

Валидировать вход по нормализованной схеме.
Применить input mapping.
Собрать HTTP request.
Выполнить вызов через reqwest.
Преобразовать ответ в нормализованный JSON.
Применить output mapping.
Вернуть итоговый результат MCP server.

8. Нюансы и ограничения

DELETE допускается, но body для него не считается обязательным сценарием совместимости.
PATCH требует аккуратной работы с частичными payload, поэтому mapping должен позволять заполнять только выбранные поля.
Успешный HTTP status сам по себе не гарантирует корректность бизнес-ответа, если response mapping не может извлечь ожидаемые данные.
REST adapter не должен содержать бизнес-логику маппинга, только transport-логику.
Загруженные JSON-примеры используются для генерации черновика, но не заменяют явную конфигурацию operation.

9. Почему REST остается отдельным протоколом

REST нельзя считать просто частным случаем другого HTTP-based интерфейса, потому что:

контракт определяется URL, методом и payload;
semantics HTTP methods важны;
поведение интеграции часто завязано на headers и auth;
UX настройки REST operation отличается от GraphQL и gRPC.

5.7 KiB Raw Blame History