API документация

Генерация случайных данных через HTTP. Все методы ниже используют GET и возвращают JSON.

Как пользоваться API

GET /api/v1/*

Внешний API доступен только зарегистрированным пользователям с подтверждённым email. Все эндпоинты, включая каталоги, требуют пользовательский Bearer-токен. До 100 результатов за запуск. Сохраняются технические пределы: до 10 000 результатов в запросе, до 20 000 значений полей в конструкторе, естественные пределы генераторов и квоты внешних сервисов. Обычный API: 60 запросов/мин.

Зарегистрируйтесь, подтвердите email и войдите. Откройте «Аккаунт» → «Токен API» → «Показать токен» и скопируйте его. Аккаунт ↗
Передавайте токен только в заголовке Authorization: Bearer TOKEN. Замените TOKEN своим значением без кавычек вокруг него. Публичный ключ Supabase для этого не подходит.
Выберите эндпоинт ниже, скопируйте URL и задайте параметры из его таблицы. Примеры используют генератор целых чисел; изменяйте путь и параметры для других генераторов.

Сейчас используется временный access token сессии Supabase, а не постоянный API-ключ. Его срок задаётся настройками проекта. При 401 снова откройте аккаунт, войдите при необходимости и скопируйте актуальный токен. Статический токен в скрипте сам не обновляется. Не публикуйте токен: он даёт права вашей сессии.

Запрос

Запросы: GET по HTTPS; параметры передаются в query string, без JSON-тела. Кодируйте значения через URLSearchParams или аналог библиотеки; один параметр — одно значение. count — положительное целое, в большинстве генераторов до 10000; точные пределы и доступные значения указаны ниже. Открытие ссылки без заголовка токена вернёт 401.

GET https://rand.by/api/v1/integer?count=3&min=1&max=100
Authorization: Bearer TOKEN

Ответ

Успех: HTTP 200 и JSON с массивом items. Тип элементов зависит от генератора. Каталоги имеют отдельную структуру: money/currencies возвращает asOf и items, geo/catalog — объект каталога. Ответы не кешируются. Сначала проверяйте HTTP-статус, затем разбирайте JSON; пример чисел справа условный.

{ "items": [42, 7, 91] }

Готовые примеры и настройка

Для серверных примеров задайте RANDBY_API_TOKEN в окружении процесса; команда export показана во вкладке curl, вариант Windows — в PowerShell. Затем выполните подготовку выбранного примера. Не сохраняйте секреты в Git, URL, логах или публичных переменных Nuxt. В браузере используйте только токен текущего пользователя; общий токен храните на сервере. Пример маршрута Nuxt требует вашей собственной авторизации и ограничения частоты, иначе он откроет общий доступ к вашему токену через прокси.

Подготовка

export RANDBY_API_TOKEN='PASTE_TOKEN_HERE'

curl

curl --fail-with-body --max-time 15 --get 'https://rand.by/api/v1/integer' \
  --header "Authorization: Bearer $RANDBY_API_TOKEN" \
  --data-urlencode 'count=3' \
  --data-urlencode 'min=1' \
  --data-urlencode 'max=100'

Ошибки и действия
400	Неверные параметры, повторяющиеся значения или превышение технического предела. Проверьте таблицу эндпоинта и исправьте запрос.
401	Токен отсутствует, недействителен или истёк; также проверьте подтверждение email. Получите актуальный токен в аккаунте и повторите запрос.
404	Неизвестный путь или генератор. Проверьте URL; для API не нужен языковой префикс вроде /en.
429	Превышена частота публичного демо. Подождите минуту; не повторяйте запросы в цикле без задержки.
503	Сервис проверки авторизации временно недоступен или не настроен. Повторите позже; проверьте конфигурацию Supabase, если вы владелец сервиса.

Песочница ниже работает без токена через отдельный демо-маршрут: до 10 записей и 60 запросов в минуту на IP. Это демонстрация. Внешний /api/v1/* остаётся закрытым и использует технические пределы эндпоинтов.

Генерация по seed для CI

POSTPremium

Одинаковые схема и seed дают одинаковые тестовые данные при той же версии генерации и тех же справочниках.

API-ключи для CI · Создайте ключ и сохраните его в CI как секрет RANDBY_CI_KEY.
Экспорт схемы · Экспортируйте схему Builder в JSON и храните рядом с тестовыми данными.
Выберите пример ниже и запустите его из папки с экспортированной схемой.

Передавайте CI-ключ Premium в заголовке Authorization и храните его в секретах CI. Ключ действует 90 дней. Для ротации создайте новый ключ, обновите секрет и отзовите старый после успешного запуска.

Запрос

Отправьте POST-запрос с заголовком Content-Type application/json. В теле запроса три поля.

schema: Обязательный JSON-объект. Передайте содержимое экспортированной схемы Builder вместе со связанными таблицами.
seed: Обязательная непустая строка до 128 символов. Оставьте seed прежним для повтора или измените его для новой выборки.
version: Необязательная версия генерации. Текущее значение и значение по умолчанию — v1. В CI указывайте её явно.

POST https://rand.by/api/builder/ci/generate
Authorization: Bearer CI_KEY
Content-Type: application/json

{
  "schema": {
    "version": 1,
    "count": 2,
    "fields": [
      {
        "id": "id",
        "path": "id",
        "generator": "sequence",
        "output": "value",
        "settings": {
          "start": 1,
          "step": 1
        },
        "array": false,
        "size": 1,
        "nullPercent": 0
      }
    ]
  },
  "seed": "fixtures-v1",
  "version": "v1"
}

Ответ

Ответ содержит version и либо items и columns, либо tables для схемы с несколькими таблицами. Для повторного прогона используйте ту же схему и seed.

Одна таблица

{
  "version": "v1",
  "columns": [
    "id"
  ],
  "items": [
    {
      "id": 1
    },
    {
      "id": 2
    }
  ]
}

Несколько таблиц

{
  "version": "v1",
  "tables": [
    {
      "id": "main",
      "name": "users",
      "columns": [
        "id"
      ],
      "items": [
        {
          "id": 1
        }
      ]
    },
    {
      "id": "orders",
      "name": "orders",
      "columns": [
        "user_id"
      ],
      "items": [
        {
          "user_id": 1
        }
      ]
    }
  ]
}

Храните схему, seed и версию генерации в репозитории или настройках задачи. Изменения схемы, генератора или справочников могут изменить результат. Данные по seed предназначены для тестов.

До 8 таблиц, 10 000 строк суммарно и 20 000 значений за запрос с учётом элементов массивов. Лимит — 60 запросов в минуту на аккаунт.

Готовые примеры и настройка

Примеры читают randby-builder-schema.json и записывают fixtures.json. Сохраните код под именем из блока «Подготовка». В GitHub Actions добавьте шаг после checkout и используйте файл в следующем шаге.

Подготовка

bash --version
curl --version
jq --version
bash generate-fixtures.sh

curl + jq

set -euo pipefail
: "${RANDBY_CI_KEY:?RANDBY_CI_KEY is required}"

jq -n --slurpfile schema randby-builder-schema.json --arg seed 'fixtures-v1' \
  '{schema: $schema[0], seed: $seed, version: "v1"}' |
  curl --fail --silent --show-error --max-time 60 'https://rand.by/api/builder/ci/generate' \
    --header "Authorization: Bearer $RANDBY_CI_KEY" \
    --header 'Content-Type: application/json' \
    --data-binary @- --output fixtures.json

Ошибки и действия
400	Некорректный JSON, seed, версия или схема. При ошибке схемы проверьте data.code и data.field в ответе.
401	Ключ отсутствует, неверен, просрочен или отозван, либо Premium неактивен. Проверьте секрет и аккаунт.
413	Тело запроса больше 260 КиБ. Уменьшите размер схемы.
429	Превышен лимит запросов. Подождите минуту перед повтором.
502	Сервер не смог сгенерировать данные. Если схема корректна, повторите запрос позже.
503	Сервис проверки ключей временно недоступен. Повторите запрос позже.

Эндпоинты API

Выберите метод, изучите его параметры и откройте песочницу. Измените строку запроса и выполните GET-запрос, чтобы увидеть реальный JSON-ответ сервера.

URL сам по себе не авторизует запрос. Получите токен в аккаунте и передайте его в заголовке Authorization: Bearer TOKEN. Не добавляйте токен в URL. Для проверки без токена используйте песочницу в документации. Как пользоваться API

Целые числа

GET /api/v1/integer

Генерация отрицательных и положительных целых чисел

Параметры
Название	Описание	Значение по умолчанию
count	Количество генерируемых чисел (Целое число от 1 до 10000)	100
min	Левая граница диапазона генерируемых чисел (Целое число от -100000000 до 100000000)	-100
max	Правая граница диапазона генерируемых чисел (Целое число от -100000000 до 100000000)	100
round	Округление полученных чисел до ближайших кратных заданному в этом параметре числу. Например, нужно получить набор чисел, кратных 50. Таким образом 2489 станет 2500, 131 станет 100, а 851 станет 900	0

Пример URL с параметрамиhttps://rand.by/api/v1/integer?count=10