7.8 KiB
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-datarequest 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_urlmethodpath_templateheadersauth_profileinput_schemainput_mappingoutput_schemaoutput_mappingtool_description
На слое MCP REST operation всегда выглядит как вызов запрос -> ответ с фиксированной схемой входа и выхода.
5. Как оператор настраивает REST operation
- Указывает
base_url. - Выбирает HTTP method.
- Указывает
path_template. - При необходимости загружает пример входного и выходного
JSON. - Система строит черновую схему и стартовые связи полей.
- Описывает или уточняет входные MCP-параметры.
- Сопоставляет параметры с
Path,Query,HeaderиBodyв визуальном конструкторе. - Указывает, откуда извлекать полезные данные в ответе.
- При необходимости открывает блок Дополнительно и уточняет YAML/JSONPath вручную.
- Запускает тест.
- Публикует 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 должен:
- Валидировать вход по нормализованной схеме.
- Применить input mapping.
- Собрать HTTP request.
- Выполнить вызов через
reqwest. - Преобразовать ответ в нормализованный JSON.
- Применить output mapping.
- Вернуть итоговый результат 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.