crank/docs/protocols/rest.md

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.