---
referenceVersion: 2
---

# Запросы к 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 не требуется. Протокольные конверты выражаются теми же входами:

```yaml [GraphQL поверх HTTP · фрагмент v2]
- id: query
  block: http
  params:
    url: "{inputs.graphql_url}"
    method: POST
    json:
      query: "{inputs.query}"
      variables: "{inputs.variables}"
```

```yaml [JSON-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-транспорты из этой поддержки не следуют.

<span id="решения-по-параметрам"></span>

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

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

<span id="модули-и-поставка"></span>

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

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

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

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