Architettura e Struttura dei Dati
L'API funziona come un archivio indipendente e storico dei dati di Reddit, non essendo un servizio ufficiale in tempo reale. Le risposte restituiscono record piatti che non seguono necessariamente l'ordine cronologico o quello di rilevanza. L'ordinamento predefinito segue l'ordine interno del documento di archiviazione, il che significa che i dati più recenti non sono sempre i primi.
I dati restituiti sono record piatti, privi di strutture gerarchiche complesse assemblate dal server. Questo significa che non esiste un albero completo delle conversazioni fornito direttamente dall'API. I client possono raggruppare i dati localmente se i campi parent_id e link_id sono presenti nelle risposte, ma questa operazione non garantisce una completezza assoluta.
L'utilizzo dei filtri parent_id o link_id non è disponibile come parametro di query diretto. Solo l'endpoint /v1/item richiede esplicitamente un identificatore univoco per il recupero di un elemento specifico. Gli endpoint per i post e i commenti non richiedono alcun identificatore, permettendo ricerche più ampie e flessibili sui dati archiviati.
Endpoint e Filtri di Ricerca
I principali endpoint includono /v1/search, /v1/posts, /v1/comments, /v1/item, /v1/subreddits e /v1/status. Per /v1/search, /v1/posts e /v1/comments sono ammessi al massimo cento record per richiesta e cento pagine per query. La scansione delle pagine rimane limitata e non garantisce una copertura completa dell’archivio o un’esportazione di tutti i record corrispondenti. Per confrontare due temi, documenta le pagine effettivamente lette insieme ai filtri.
I filtri disponibili includono query testuale, subreddit, autore, tipo di contenuto e intervalli di date ISO. È possibile specificare un punteggio minimo, che agisce esclusivamente come filtro e mai come controllo di ordinamento. Il limite di recupero è impostato tra uno e cento record, con la possibilità di navigare tra le pagine da una a cento.
Il parametro kind accetta soltanto i valori letterali post e comment. I totali paginati vanno letti con la loro relazione: eq indica un totale esatto per la risposta, gte un limite inferiore e unknown l’assenza di un totale affidabile, che può essere null. Un limite inferiore non è un conteggio esatto. Anche un totale esatto non dimostra che l’archivio contenga tutta la storia della comunità o che ogni risultato sia stato scaricato.
Errori HTTP e Gestione dei Crediti
Gli errori del protocollo usano codici numerici ASCII. HTTP 400 indica una richiesta non valida, mentre 401 segnala una chiave mancante o non valida. Il codice 402 indica crediti insufficienti per il recupero; 429 segnala il superamento del limite di frequenza. Registra il codice effettivamente ricevuto senza sostituirlo con una supposizione sul contenuto: un errore tecnico non significa che manchino testi relativi al tema cercato.
Ogni recupero di record con successo costa un credito, incluso il caso in cui il risultato sia vuoto. Gli errori a monte restituiscono il credito speso, garantendo che l'utente non perda fondi per fallimenti non dovuti. L'endpoint /v1/status è pubblico e non comporta alcun costo, fornendo una conferma statica che il server risponda correttamente alle richieste.
I crediti pagati non scadono; la ricarica minima è di $50 per 50000 crediti, al prezzo di $1 per mille richieste riuscite. Per HTTP 401 controlla la chiave e l’autenticazione; per 402 verifica il saldo; per 429 riduci la frequenza e attendi prima di riprovare. Il cambio di chiave o un pagamento non risolvono un limite di frequenza. Chiavi e saldi appartengono al dominio della registrazione e non sono condivisi nell’intera rete.
