Files
crank/docs/protocols/rest.md
T

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-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.