API dokumentacja

Generuj losowe dane przez HTTP. Poniższe metody używają GET i zwracają JSON.

Jak korzystać z API

GET /api/v1/*

Zewnętrzne API jest dostępne dla zarejestrowanych użytkowników z potwierdzonym adresem email. Każdy endpoint, także katalogi, wymaga tokenu Bearer użytkownika. Do 100 wyników na uruchomienie. Pozostają limity techniczne: 10 000 wyników na żądanie, 20 000 wartości pól w kreatorze, naturalne limity generatorów i limity dostawców. Standardowe API: 60 żądań/min.

Zarejestruj się, potwierdź email i zaloguj. Otwórz Konto → Token API → Pokaż token i skopiuj go. Konto ↗
Przesyłaj token tylko w nagłówku Authorization: Bearer TOKEN. Zastąp TOKEN własną wartością bez cudzysłowów. Publiczny klucz Supabase nie wystarczy.
Wybierz endpoint poniżej, skopiuj URL i użyj parametrów z tabeli. Przykłady dotyczą liczb całkowitych; dla innych generatorów zmień ścieżkę i parametry.

To tymczasowy token sesji Supabase, a nie stały klucz API. Czas ważności określa konfiguracja projektu. Przy 401 otwórz konto, zaloguj się w razie potrzeby i skopiuj aktualny token. Statyczny token w skrypcie nie odnawia się sam. Zachowaj go w tajemnicy: nadaje uprawnienia Twojej sesji.

Żądanie

Żądania: GET przez HTTPS, parametry w query string, bez treści JSON. Koduj wartości przez URLSearchParams lub odpowiednik biblioteki; jedna wartość na parametr. count to dodatnia liczba całkowita, zwykle do 10000; dokładne limity są poniżej. Link bez nagłówka tokenu zwróci 401.

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

Odpowiedź

Sukces: HTTP 200 i JSON z tablicą items. Typ zależy od generatora. money/currencies zwraca asOf i items, geo/catalog — obiekt katalogu. Odpowiedzi nie są buforowane. Najpierw sprawdzaj status HTTP, potem JSON; liczby w przykładzie są poglądowe.

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

Gotowe przykłady i konfiguracja

Dla przykładów serwerowych ustaw RANDBY_API_TOKEN w środowisku procesu: export jest w curl, wariant Windows w PowerShell. Wykonaj przygotowanie wybranego przykładu. Nie zapisuj sekretów w Git, URL, logach ani publicznych zmiennych Nuxt. W przeglądarce używaj tylko tokenu aktualnego użytkownika; wspólne tokeny trzymaj na serwerze. Trasa Nuxt wymaga własnego uwierzytelniania i limitu żądań, inaczej proxy udostępni dostęp z Twoim tokenem.

Przygotowanie

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'

Błędy i działania
400	Nieprawidłowe parametry, powtórzone wartości lub przekroczony limit techniczny. Sprawdź tabelę i popraw żądanie.
401	Brak tokenu, nieważny lub wygasły token; sprawdź też potwierdzenie email. Pobierz aktualny token w koncie.
404	Nieznana ścieżka lub generator. Sprawdź URL; API nie używa prefiksu języka, np. /en.
429	Przekroczony limit publicznego demo. Odczekaj minutę i nie ponawiaj żądań bez przerwy.
503	Usługa uwierzytelniania jest niedostępna lub nieskonfigurowana. Spróbuj później; właściciel powinien sprawdzić Supabase.

Piaskownica działa bez tokenu przez oddzielną trasę demo: do 10 rekordów i 60 żądań na minutę na IP. Zewnętrzne /api/v1/* pozostaje zamknięte i stosuje techniczne limity endpointów.

Generowanie z seedem w CI

POSTPremium

Ten sam schemat i seed dają te same dane testowe przy tej samej wersji i katalogach danych.

Klucze API do CI · Utwórz klucz i zapisz go jako sekret CI RANDBY_CI_KEY.
Eksportuj schemat · Wyeksportuj schemat Buildera jako JSON i zachowaj z danymi testowymi.
Wybierz przykład i uruchom go w folderze wyeksportowanego schematu.

Prześlij klucz CI Premium w nagłówku Authorization i zapisz go jako sekret CI. Klucz działa 90 dni. Utwórz nowy klucz, zaktualizuj sekret i unieważnij stary po udanym uruchomieniu.

Żądanie

Wyślij POST z Content-Type application/json. Treść JSON zawiera trzy pola.

schema: Wymagany obiekt JSON. Przekaż wyeksportowany schemat Buildera wraz z powiązanymi tabelami.
seed: Wymagany niepusty ciąg do 128 znaków. Zachowaj go, aby powtórzyć wynik, lub zmień, aby uzyskać nową próbkę.
version: Opcjonalna wersja generatora. Aktualna i domyślna wartość to v1. W CI podaj ją jawnie.

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"
}

Odpowiedź

Odpowiedź zawiera version oraz items i columns albo tables dla wielu tabel. Do powtórzenia użyj tego samego schematu i seedu.

Jedna tabela

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

Wiele tabel

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

Zapisz schemat, seed i wersję w repozytorium lub ustawieniach zadania. Zmiana schematu, generatora lub katalogów może zmienić wynik. Dane służą do testów.

Do 8 tabel, łącznie 10 000 wierszy i 20 000 wartości na żądanie z elementami tablic. Limit 60 żądań na minutę na konto.

Gotowe przykłady i konfiguracja

Przykłady czytają randby-builder-schema.json i zapisują fixtures.json. Zapisz kod pod nazwą z instrukcji konfiguracji. W GitHub Actions dodaj krok po checkout i użyj pliku w kolejnym kroku.

Przygotowanie

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

Błędy i działania
400	Nieprawidłowy JSON, seed, wersja lub schemat. Przy błędzie schematu sprawdź data.code i data.field.
401	Brak klucza, klucz nieważny, wygasły lub unieważniony albo Premium nieaktywne. Sprawdź sekret i konto.
413	Treść przekracza 260 KiB. Zmniejsz schemat.
429	Przekroczono limit żądań. Odczekaj minutę.
502	Serwer nie wygenerował danych. Jeśli schemat jest poprawny, spróbuj później.
503	Weryfikacja kluczy jest chwilowo niedostępna. Spróbuj później.

Endpointy API

Wybierz metodę, przejrzyj parametry i otwórz piaskownicę. Zmień zapytanie i wykonaj żądanie GET, aby zobaczyć rzeczywistą odpowiedź JSON.

Sam adres URL nie autoryzuje żądania. Pobierz token na swoim koncie i przekaż go w nagłówku Authorization: Bearer TOKEN. Nie dodawaj tokenu do adresu URL. Aby przetestować API bez tokenu, użyj piaskownicy w dokumentacji. Jak korzystać z API

Liczby całkowite

GET /api/v1/integer

Generowanie dodatnich i ujemnych liczb całkowitych

Parametry
nazwa	Opis	Wartość domyślna
count	Liczba wygenerowanych liczb (liczba całkowita od 1 do 10000)	100
min	Lewa granica zakresu generowanych liczb (liczba całkowita od -100000000 do 100000000)	-100
max	Prawa granica zakresu generowanych liczb (liczba całkowita od -100000000 do 100000000)	100
round	Zaokrąglanie otrzymanych liczb do najbliższej wielokrotności liczby określonej w tym polu. Na przykład potrzebujesz zestawu liczb będących wielokrotnością 50. Zatem 2489 staje się 2500, 131 staje się 100, a 851 staje się 900	0

Przykładowy URL z parametramihttps://rand.by/api/v1/integer?count=10