Запросы к API

http отправляет запрос и возвращает ответ сервиса.

Параметры

Параметр	Назначение	По умолчанию
url	Адрес	Обязательно
method	HTTP-метод	GET
query, headers	Параметры URL, заголовки	{}
json	JSON любого типа, включая массив и null	Не передаётся
content	Текст или FileRef для сырого тела	Не передаётся
form	Поля формы	Не передаётся
files	Имена полей → FileRef	Не передаётся
response	text или file	text
response_headers	Какие заголовки ответа сохранить	[]
timeout_seconds	Лимит одной попытки	30
max_response_bytes	Размер распакованного ответа	33554432
retry	max_attempts, delay_seconds	GET/HEAD: 3 попытки, пауза 1 с; остальные: 1 попытка
on_transport_error	fail или return	fail

Один режим тела: json, content или form/files. Файлы совместимы с полями формы. Явный JSON null отличается от отсутствия тела. Для content тип содержимого задаётся через headers; байты файла берутся из FileRef.

Пример

YAMLФрагмент формата v2

- id: catalog
  block: http
  params:
    url: "{inputs.catalog_url}"
    method: GET
    query:
      limit: 20
    response_headers: [content-type]

Результат

status_code, headers, body, json, file, redirect_url, transport_error.

json/file могут быть null; при получении файла body пустой. headers содержит только запрошенные заголовки с именами в нижнем регистре. Редирект возвращается, но не выполняется автоматически.

Поведение

HTTP-код проверяется через validate. При сетевой ошибке fail останавливает шаг, return возвращает status_code=0 и тип ошибки. Это не доказывает, что запись на стороне сервиса не состоялась.

Повторы только для GET/HEAD: до 5 попыток, пауза 0–10 с. Запись автоматически не повторяется.

Пример: Google API

Workflow получает адрес сервисного аккаунта, scope и ключ → crypto подписывает JWT → http обменивает его на access_token → validate проверяет ответ → http обращается к Sheets или Drive с Bearer-токеном.

ID таблицы, папки и диапазон передаются входами. Строки ответа обрабатывает data; он сам к Google не подключается. Получение токена можно вынести в вызываемый workflow.

Нужен ли отдельный api

Предлагаю оставить http: API — назначение сервиса, HTTP — способ вызова. REST, GraphQL и RPC поверх HTTP различаются адресом, заголовками и телом, которые блок уже принимает. Ещё один api с теми же параметрами дублировал бы контракт.

Авторизацию, пагинацию и повторяемые вызовы конкретного сервиса можно собрать в вызываемый workflow с явными входами и выходами. Для gRPC или WebSocket потребуется отдельное обсуждение транспорта: переименование в api само по себе их не поддержит.

REST, GraphQL и JSON-RPC

Общая реализация http кодирует URL, заголовки и тело и разбирает ответ. Заранее задавать в ней бизнес-методы каждого API не требуется. Протокольные конверты выражаются теми же входами:

YAMLGraphQL поверх HTTP · фрагмент v2

- id: query
  block: http
  params:
    url: "{inputs.graphql_url}"
    method: POST
    json:
      query: "{inputs.query}"
      variables: "{inputs.variables}"

YAMLJSON-RPC поверх HTTP · фрагмент v2

- id: rpc
  block: http
  params:
    url: "{inputs.rpc_url}"
    method: POST
    json:
      jsonrpc: "2.0"
      method: "{inputs.method}"
      params: "{inputs.parameters}"
      id: "{inputs.request_id}"

HTTP 200 не гарантирует успех GraphQL/JSON-RPC: у них бывают errors/error в JSON. Проверка ответа и соответствия id выражается через validate; повторяемые конверты, авторизация и пагинация — через call/loop. Другие RPC-транспорты из этой поддержки не следуют.

Параметры операций

Используются JSON, формы, файлы, выбор заголовков ответа и ограничение размера. Добавляем сырой content, чтобы не выдавать JSON за любой HTTP-body. В v2 переименовываем старое body в явное json, timeout в timeout_seconds, объединяем retry_* в retry. Это миграция, а не незаметная смена v1. Старый skip_if переносится в общий when с инверсией смысла; отдельный флаг блоку больше не нужен.

Плагины и установка

В составе блока: Запросы HTTP/1.1: JSON, текст, формы, файлы, таймауты и повторы.

Плагин	Возможности
http2	Транспорт HTTP/2

REST, GraphQL и JSON-RPC поверх HTTP используют обычные запросы. Авторизация и пагинация собираются в workflow.