120 lines
7.8 KiB
Markdown
120 lines
7.8 KiB
Markdown
# 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.
|