Endpointy HTTP API

GET /raw

Zwraca binarny bufor losowych bajtów z centralnej puli entropii. Domyślny rozmiar to 64 KB, z możliwością określenia parametru `bytes` od 1 do 1 048 576 B.

curl -s "https://entropy.sparksome.pl/raw?bytes=32" | xxd -p

GET /raw/stream

Ciągłe strumieniowanie binarnych bajtów losowości przez połączony socket HTTP. Przydatne dla usług o wysokim zapotrzebowaniu na entropię.

curl -N -s "https://entropy.sparksome.pl/raw/stream?bytes=65536" > entropy_stream.bin

GET /download/entropy

Zwraca plik binarny `.bin` z nagłówkiem `Content-Disposition: attachment` do wygodnego pobierania z przeglądarki lub skryptów.

GET /healthz

Zwraca status operacyjny węzła w formacie JSON: dostępna pula bajtów, stan odbiorników SDR, wskaźniki odrzuceń i czasy odpowiedzi.

Przykłady integracji

> Python (requests / urllib)

import requests

response = requests.get("https://entropy.sparksome.pl/raw", params={"bytes": 64})
if response.status_code == 200:
    random_bytes = response.content
    print("Pobrano bytes:", random_bytes.hex())

> JavaScript (Node.js fetch)

const res = await fetch("https://entropy.sparksome.pl/raw?bytes=32");
const buffer = await res.arrayBuffer();
const bytes = new Uint8Array(buffer);
console.log("Random Bytes:", bytes);

> Shell / cURL

# Fetch 16 random bytes as hex
curl -s "https://entropy.sparksome.pl/raw?bytes=16" | xxd -p

Limity i ochrona przed przeciążeniem

Aby chronić infrastrukturę przed wyczerpaniem puli entropii, Nginx wymusza limity żądań. Standardowe endpointy pozwalają na 10 req/s, a cięższe pobrania /raw są ograniczone do 2-3 req/s na IP.

HTTP 429 Too Many Requests — w przypadku przekroczenia limitu odczekaj zadaną liczbę sekund podaną w nagłówku Retry-After.