Rotte API e Strutturazione dei Dati
L'API fornisce sei rotte principali per l'accesso all'archivio indipendente: /v1/search, /v1/posts, /v1/comments, /v1/item, /v1/subreddits e /v1/status. Questi endpoint permettono di interrogare i dati storici in modo granulare. Non si tratta di un servizio live di Reddit, ma di un archivio storico. Le richieste di recupero richiedono una chiave valida tramite Authorization: Bearer o X-API-Key. /v1/status è pubblico e non richiede la chiave. L'archivio non è affiliato ufficialmente a Reddit né garantisce dati in tempo reale.
Le risposte dell'API sono strutture piatte, non alberi di thread assemblati dal server. I campi parent_id e link_id, se presenti, possono essere raggruppati dal client per ricostruire le conversazioni localmente. Non c'è una garanzia di presenza di tutti i record collegati o di conversazioni esaurienti. Le rotte /v1/posts e /v1/comments non richiedono un parametro id, mentre /v1/item sì. Questa distinzione è cruciale per ottimizzare le chiamate nelle automazioni.
L'endpoint /v1/status restituisce una descrizione statica sull'archivio indipendente e conferma che il server HTTP risponde. Non monitora la salute del backend di ricerca, la copertura dei dati o la completezza del dataset. È una risposta pubblica e non viene addebitata, a differenza delle richieste di recupero dati. Utilizza questa route per verificare la connettività di base senza consumare crediti, mantenendo il controllo sui costi di automazione.
Filtri, Ordinamento e Limiti di Pagina
I filtri supportati includono q, subreddit, author, kind, date from e to in formato YYYY-MM-DD in UTC, con il giorno to incluso, min_score, limit e page. q cerca in title e text, combinando più termini con AND nello stesso campo corrispondente. Il parametro kind accetta solo i valori post e comment. Il filtro min_score agisce esclusivamente come filtro, mai come controllo di ordinamento. L'ordine di recupero utilizza l'ordine _doc dell'archivio, che non è cronologico, né basato sulla rilevanza o sul punteggio. Le iterazioni di pagina limitate a cento non garantiscono una copertura completa o un'ingestione esauriente di tutti i record corrispondenti.
Ogni richiesta può restituire al massimo cento record e le query possono paginare fino a cento pagine. I totali di paginazione includono una relazione: eq indica un conteggio esatto, gte un limite inferiore e unknown indica un totale sconosciuto, che può essere null. Un limite inferiore non va interpretato come conteggio esatto. Nessuno di questi totali dimostra la copertura completa dell'archivio. Questa dinamica è essenziale per automazioni che richiedono un'estrazione completa, evitando promesse di esaustività non verificate.
L'endpoint /v1/item richiede obbligatoriamente il parametro id per funzionare correttamente. Al contrario, le rotte di ricerca generale non lo richiedono. I subreddits supportano una ricerca per prefisso, utile per l'esplorazione. I valori delle date ISO possono essere usati per restringere il campo temporale. La combinazione di questi filtri permette di costruire query precise. È fondamentale comprendere che l'ordine _doc non riflette necessariamente l'ordine temporale dei contenuti nell'archivio storico.
Gestione Errori, Autenticazione e Pagamenti
I codici di errore devono essere gestiti con precisione: 401 indica una chiave mancante o non valida, 402 segnala crediti insufficienti e 429 avvisa per limiti di velocità. Le richieste di recupero riuscite costano un credito, anche se il risultato è vuoto. I guasti della fonte restituiscono la riserva al saldo dell'utente; le richieste non valide non addebitano crediti. I codici HTTP devono essere sempre trattati come numeri ASCII. Le chiavi API e i saldi sono specifici del tenant, non condivisi sulla rete. I controlli antiabuso della prova sono invece condivisi nella rete. Una risposta persa dal client può corrispondere a un successo già addebitato; un nuovo tentativo riuscito costa un altro credito.
L'accesso all'account avviene tramite email e password. La chiave API viene mostrata una sola volta subito dopo la registrazione, prima del pagamento, e non viene mai inviata via email automaticamente. Gli utenti possono rigenerare la chiave dopo aver confermato la password, invalidando immediatamente quella vecchia. Non esiste una funzione di reimpostazione della password o una consegna automatica. I crediti pagati non scadono. Il limite minimo di ricarica è di cinquanta dollari, con un costo di un dollaro per mille recuperi riusciti. Nessun abbonamento è disponibile.
I pagamenti possono essere effettuati con USDT TRC20 o USDC ERC20 Ethereum mainnet. L'indirizzo di ricezione e l'importo esatti sono visualizzati nella fattura creata dal server. La fattura scade un'ora dopo la creazione. Il momento del trasferimento deve essere compreso fra la creazione della fattura e 72 ore dopo la scadenza. Non è un termine per richiedere la verifica. Non esistono garanzie di velocità di trasferimento o conferma. Le risposte sono piatte e le automazioni possono raggruppare localmente i dati disponibili per ricostruire il contesto delle conversazioni archiviate.
