Endpoints HTTP API

GET /raw

Devuelve un búfer binario de bytes aleatorios de la reserva central de entropía. Tamaño por defecto: 64 KB; parámetro opcional `bytes` de 1 a 1.048.576 B.

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

GET /raw/stream

Streaming continuo de bytes aleatorios binarios sobre un socket HTTP abierto. Útil para servicios con alta demanda de entropía.

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

GET /download/entropy

Devuelve un archivo `.bin` con cabecera `Content-Disposition: attachment` para descargas desde navegador o scripts.

GET /healthz

Devuelve el estado operativo del nodo en JSON: reserva disponible, estado SDR, rechazos y tiempos de respuesta.

Ejemplos de integración

> 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

Límites y protección contra sobrecarga

Para evitar agotar la reserva de entropía, Nginx aplica límites de velocidad. Los endpoints estándar permiten 10 req/s, y las descargas /raw más pesadas 2-3 req/s por IP.

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