API дакументацыя

Генерацыя выпадковых даных праз HTTP. Усе метады ніжэй выкарыстоўваюць GET і вяртаюць JSON.

Як карыстацца API

GET /api/v1/*

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

Зарэгіструйцеся, пацвердзіце пошту і ўвайдзіце. Адкрыйце «Акаўнт» → «Токен 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	Токен адсутнічае, несапраўдны або пратэрмінаваны; праверце пацверджанне пошты. Атрымайце актуальны токен у акаўнце.
404	Невядомы шлях або генератар. Праверце URL; API не патрэбны моўны прэфікс накшталт /en.
429	Перавышана частата публічнага дэма. Пачакайце хвіліну і не паўтарайце запыты без затрымкі.
503	Сэрвіс аўтарызацыі недаступны або не наладжаны. Паўтарыце пазней; уладальніку варта праверыць Supabase.

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

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

POSTPremium

Аднолькавыя схема і seed даюць аднолькавыя даныя пры той жа версіі і тых жа даведніках.

Ключы API для 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