API-Dokumentation

Zufallsdaten über HTTP erzeugen. Alle Methoden unten verwenden GET und liefern JSON.

API verwenden

GET /api/v1/*

Die externe API ist für registrierte Nutzer mit bestätigter E-Mail verfügbar. Alle Endpunkte, auch Kataloge, benötigen ein Benutzer-Bearer-Token. Bis zu 100 Ergebnisse pro Durchlauf. Technische Grenzen bleiben: 10.000 Ergebnisse je Anfrage, 20.000 Feldwerte im Baukasten, natürliche Generatorgrenzen und Anbieterquoten. Standard-API: 60 Anfragen/Minute.

Registrieren, E-Mail bestätigen und anmelden. Unter Konto → API-Token → Token anzeigen das Token kopieren. Konto ↗
Das Token nur im Header Authorization: Bearer TOKEN senden. TOKEN ohne Anführungszeichen ersetzen. Ein öffentlicher Supabase-Schlüssel ist dafür ungeeignet.
Unten einen Endpunkt wählen, die URL kopieren und die Parameter der Tabelle verwenden. Die Beispiele nutzen den Ganzzahlgenerator; für andere Generatoren Pfad und Parameter ändern.

Dies ist ein temporäres Supabase-Sitzungstoken, kein dauerhafter API-Schlüssel. Die Gültigkeit wird im Projekt festgelegt. Bei 401 das Konto öffnen, gegebenenfalls anmelden und ein aktuelles Token kopieren. Ein statisches Token im Skript erneuert sich nicht selbst. Geheim halten: Es gewährt die Rechte Ihrer Sitzung.

Anfrage

Anfragen: GET über HTTPS mit Query-Parametern ohne JSON-Body. Werte mit URLSearchParams oder einer entsprechenden Bibliothek kodieren; ein Wert pro Parameter. count ist eine positive Ganzzahl, meist bis 10000; genaue Grenzen stehen unten. Ein Link ohne Token-Header liefert 401.

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

Antwort

Erfolg: HTTP 200 und JSON mit einem items-Array. Der Elementtyp hängt vom Generator ab. money/currencies liefert asOf und items; geo/catalog ein Katalogobjekt. Antworten werden nicht zwischengespeichert. Erst HTTP-Status prüfen, dann JSON auswerten; die Beispielzahlen sind illustrativ.

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

Beispiele und Einrichtung

Für Serverbeispiele RANDBY_API_TOKEN in der Prozessumgebung setzen: export steht bei curl, die Windows-Variante bei PowerShell. Anschließend die gewählte Vorbereitung ausführen. Keine Geheimnisse in Git, URLs, Logs oder öffentlichen Nuxt-Variablen speichern. Im Browser nur das Token des aktuellen Nutzers verwenden, gemeinsame Tokens auf dem Server halten. Die Nuxt-Route braucht eigene Anmeldung und Ratenbegrenzung, sonst öffnet der Proxy den Zugriff mit Ihrem Token.

Vorbereitung

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'

Fehler und Maßnahmen
400	Ungültige Parameter, doppelte Werte oder technische Grenze überschritten. Endpunkttabelle prüfen und Anfrage korrigieren.
401	Token fehlt, ist ungültig oder abgelaufen; auch die E-Mail-Bestätigung prüfen. Aktuelles Token im Konto abrufen.
404	Unbekannter Pfad oder Generator. URL prüfen; API-Pfade verwenden kein Sprachpräfix wie /en.
429	Anfragelimit der öffentlichen Demo erreicht. Eine Minute warten und keine Wiederholungen ohne Pause senden.
503	Authentifizierungsdienst nicht verfügbar oder nicht eingerichtet. Später erneut versuchen; Betreiber sollten Supabase prüfen.

Die Sandbox unten funktioniert ohne Token über eine eigene Demo-Route: bis zu 10 Datensätze und 60 Anfragen pro Minute je IP. Die externe /api/v1/* bleibt geschützt und nutzt die technischen Endpunktgrenzen.

Generierung mit Seed für CI

POSTPremium

Dasselbe Schema und derselbe Seed liefern bei gleicher Version und gleichen Datenkatalogen dieselben Testdaten.

API-Schlüssel für CI · Erstelle einen Schlüssel und speichere ihn als CI-Secret RANDBY_CI_KEY.
Schema exportieren · Exportiere dein Builder-Schema als JSON und lege es bei den Testdaten ab.
Wähle unten ein Beispiel und führe es im Ordner mit dem exportierten Schema aus.

Sende einen Premium-CI-Schlüssel im Authorization-Header und speichere ihn als CI-Secret. Er gilt 90 Tage. Erstelle zur Rotation einen neuen Schlüssel, aktualisiere das Secret und widerrufe den alten nach einem erfolgreichen Lauf.

Anfrage

Sende einen POST mit Content-Type application/json. Der JSON-Body enthält drei Felder.

schema: Erforderliches JSON-Objekt. Übermittle das exportierte Builder-Schema samt verknüpften Tabellen.
seed: Erforderliche, nicht leere Zeichenfolge mit bis zu 128 Zeichen. Für Wiederholungen beibehalten, für neue Stichproben ändern.
version: Optionale Generatorversion. Aktueller Wert und Standard ist v1. Gib sie in CI explizit an.

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

Antwort

Die Antwort enthält version sowie items und columns oder tables bei mehreren Tabellen. Verwende zum Wiederholen dasselbe Schema und denselben Seed.

Eine Tabelle

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

Mehrere Tabellen

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

Speichere Schema, Seed und Version im Repository oder Job. Änderungen an Schema, Generator oder Datenkatalogen können das Ergebnis ändern. Die Ausgabe ist für Tests vorgesehen.

Bis zu 8 Tabellen, insgesamt 10.000 Zeilen und 20.000 Werte je Anfrage einschließlich Array-Elementen. Pro Konto sind 60 Anfragen pro Minute möglich.

Beispiele und Einrichtung

Die Beispiele lesen randby-builder-schema.json und schreiben fixtures.json. Speichere den Code unter dem Namen aus der Einrichtung. In GitHub Actions folgt der Schritt auf Checkout. Die Datei steht späteren Schritten zur Verfügung.

Vorbereitung

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

Fehler und Maßnahmen
400	Ungültiges JSON, Seed, Version oder Schema. Bei Schemafehlern prüfe data.code und data.field.
401	Der Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen, oder Premium ist inaktiv. Prüfe Secret und Konto.
413	Der Body ist größer als 260 KiB. Verkleinere das Schema.
429	Anfragelimit überschritten. Warte eine Minute.
502	Die Daten konnten nicht erzeugt werden. Bei einem gültigen Schema versuche es später erneut.
503	Die Schlüsselprüfung ist vorübergehend nicht verfügbar. Versuche es später erneut.

API-Endpunkte

Wähle einen Endpunkt, lies die Parameter und öffne die Sandbox. Bearbeite die Anfrage und führe sie per GET aus, um die echte JSON-Antwort zu sehen.

Die URL allein autorisiert keine Anfrage. Hol dir im Konto einen Token und sende ihn im Header Authorization: Bearer TOKEN. Füge den Token nicht zur URL hinzu. Zum Testen ohne Token nutze die Sandbox in der Dokumentation. API verwenden

Ganze Zahlen

GET /api/v1/integer

Erzeugung positiver und negativer Ganzzahlen

Parameter
Name	Beschreibung	Standardwert
count	Anzahl der generierten Zahlen (Ganzzahl von 1 bis 10000)	100
min	Linker Rand des Bereichs der generierten Zahlen (Ganzzahlzahl von -100000000 bis 100000000)	-100
max	Rechter Rand des Bereichs der generierten Zahlen (Ganzzahlzahl von -100000000 bis 100000000)	100
round	Die empfangenen Zahlen werden auf das nächste Vielfache der in diesem Feld angegebenen Zahl gerundet. Beispielsweise müssen Sie eine Reihe von Zahlen erhalten, die ein Vielfaches von 50 sind. So wird 2489 zu 2500, 131 zu 100 und 851 zu 900	0

Beispiel-URL mit Parameternhttps://rand.by/api/v1/integer?count=10