# 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`
- тестовый вызов перед публикацией

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

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

## 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 всегда выглядит как вызов `запрос -> ответ` с фиксированной схемой входа и выхода.

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

1. Указывает `base_url`.
2. Выбирает HTTP method.
3. Указывает `path_template`.
4. При необходимости загружает пример входного и выходного `JSON`.
5. Система строит черновую схему и стартовый mapping.
6. Описывает или уточняет входные MCP-параметры.
7. Сопоставляет параметры с `path`, `query`, `headers` и `body`.
8. Указывает, откуда извлекать полезные данные в ответе.
9. При необходимости уточняет mapping через `JSONPath`.
10. Запускает тест.
11. Публикует 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 должен:

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

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

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

## 9. Почему REST выделен как основной сценарий Community

REST выбран как основной сценарий Community, потому что:

- контракт определяется URL, методом и payload;
- semantics HTTP methods важны;
- поведение интеграции часто завязано на headers и auth;
- REST легко проверять через простой test run до публикации MCP tool.