# REST ## 1. Роль протокола в проекте REST - базовый и первый по очередности реализации протокол платформы. На нем должна быть обкатана общая модель `Operation`, схема входа и выхода, маппинг, тестовый запуск и публикация MCP tool. ## 2. Что поддерживается в целевом продукте - HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS` - загрузка примера входного `JSON` - загрузка примера выходного `JSON` - path parameters - query parameters - headers и cookie parameters - JSON, `application/x-www-form-urlencoded` и `multipart/form-data` request body - JSON response body и явный no-content outcome - auth: `Bearer`, `Basic`, API key - timeout и базовые transport settings - request mapping - response mapping - автогенерация чернового mapping - ручная донастройка через `JSONPath` - тестовый вызов перед публикацией ## 3. Что отложено - XML payload как основной формат - webhooks - long polling как специальный режим ## 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. Система строит черновую схему и стартовые связи полей. 6. Описывает или уточняет входные MCP-параметры. 7. Сопоставляет параметры с `Path`, `Query`, `Header` и `Body` в визуальном конструкторе. 8. Указывает, откуда извлекать полезные данные в ответе. 9. При необходимости открывает блок **Дополнительно** и уточняет YAML/JSONPath вручную. 10. Запускает тест. 11. Публикует operation как MCP tool. ## 6. Требования к маппингу Input mapping должен поддерживать: - `$.mcp.* -> $.request.path.*` - `$.mcp.* -> $.request.query.*` - `$.mcp.* -> $.request.headers.*` - `$.mcp.* -> $.request.cookies.*` - `$.mcp.* -> $.request.body.*` - константы - значения по умолчанию Если endpoint поддерживает несколько request media types, `content_type` и `body` образуют одну пару: selector выбирает schema и wire serialization. Для одного формата media type фиксируется в contract. 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. Multipart binary field принимает inline object с обязательным строковым `data_base64` и необязательными строковыми `filename`/`content_type`. Base64 использует standard alphabet и padding, без whitespace и data-URI. Пустая строка задаёт файл из нуля байтов. Массив файлов передаётся массивом таких объектов; каждый элемент становится отдельной частью. Если `filename` отсутствует, adapter не добавляет и не угадывает его. MIME выбирается из `content_type` аргумента, единственного source MIME либо `application/octet-stream`, если source не задаёт ограничения. При нескольких source MIME нужен явный выбор. Неверные metadata, MIME и base64 отклоняются до outbound I/O. Лимит `CRANK_OUTBOUND_MAX_REQUEST_BYTES` применяется ко всему сериализованному body, включая multipart boundary и headers частей. Для optional body отсутствие обоих полей `content_type`/`body` означает отсутствие HTTP body. Неполная пара ошибочна; `body: null` разрешён только nullable schema выбранного формата. Параметры с wire names `body` или `content_type` получают отдельные aliases и не подменяют selector. Сохранённые Operations без typed request contract продолжают сериализовать body как JSON, сохраняя ранее настроенный Content-Type. Для typed contract заголовок формируется выбранным encoder в единственном экземпляре. Если mapped cookie-параметры конфликтуют с существующим Cookie (в том числе из Auth Profile), запрос отклоняется до outbound I/O: пользовательские параметры не заменяют credentials. ## 8. Нюансы и ограничения - Body contract определяется исходным endpoint, включая `DELETE`. - `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.