Scoprire nomi e cercare contenuti sono attività diverse
Parti dall’unità che la tua applicazione deve ricevere. Per un nome di comunità in un selettore o catalogo locale, /v1/subreddits offre una ricerca per prefisso. Per il testo di post e commenti occorre un percorso di contenuto. Il servizio è un archivio storico indipendente, senza connessione ufficiale o in diretta con Reddit. Mostra questa distinzione nell’interfaccia per non presentare un catalogo parziale come l’elenco attuale di tutte le comunità.
Prova https://api.redditapihub.com/v1/subreddits?prefix=program&limit=3, l’esempio della pagina iniziale. prefix seleziona nomi che iniziano con program e limit chiede al massimo tre voci. Sono ammessi soltanto prefix e limit: non aggiungere page, q o subreddit. Conserva i nomi effettivamente ricevuti. count non garantisce un conteggio globale esatto e relation=unknown con total=null non significa che nessuna comunità sia rimasta fuori dall’elenco.
Quando viene scelto un nome ricevuto, la tua applicazione può usarlo come filtro subreddit in /v1/search. È un altro recupero, non una prosecuzione automatica del catalogo o una promessa di contesto completo. q cerca testo, non nomi di comunità. Trovare programming nell’elenco o ricevere record di quel subreddit non dimostra la presenza di tutti i suoi post e commenti storici. Pianifica esplicitamente questo secondo passaggio e il suo consumo.
Scegliere il tipo di record senza inventare gerarchie
Usa /v1/search se interessano entrambi i tipi di contenuto. /v1/posts aggiunge una restrizione ai post e /v1/comments ai commenti. Non presumere che search restituisca soltanto riassunti e posts una versione completa: questa differenza nei campi restituiti non fa parte del contratto. I percorsi forniscono i campi archiviati disponibili, la cui presenza può variare. Mantieni riconoscibile un valore assente invece di riempire lo schema locale con ipotesi.
Per un identificatore noto, /v1/item?id=... cerca un singolo record e richiede id. I percorsi di ricerca non accettano id come filtro. La consultazione puntuale non percorre automaticamente risposte o antenati e il record può non essere disponibile. Un campo parent_id o link_id presente permette collegamenti locali tra dati ricevuti, senza creare un filtro aggiuntivo né dimostrare che tutta la conversazione o la catena dei record precedenti sia rappresentata.
Per search, posts e comments i parametri sono q, subreddit, author, kind, from, to, min_score, limit e page. kind conserva i valori letterali post e comment. from/to usano YYYY-MM-DD e filtrano created_utc in UTC, includendo l’intero giorno finale. min_score applica una soglia senza ordinare. La consegna segue _doc, non cronologia, rilevanza o punteggio. Un ordinamento locale riorganizza soltanto i record già ricevuti.
Convalidare le risposte e stimare il costo del percorso
Nei percorsi di contenuto, limit e page vanno da 1 a 100 e ogni richiesta riceve una pagina. Interpreta eq come totale esatto della query, gte come limite inferiore e unknown come assenza di un totale affidabile. Né un totale esatto né percorrere pagine o suddividere date dimostra un download esaustivo. Conserva la risposta e i suoi limiti prima di aggiornare l’avanzamento locale. La documentazione specifica i parametri ammessi per ciascun percorso.
Per il recupero protetto usa X-API-Key: <chiave> oppure Authorization: Bearer <chiave> e conserva il segreto sul server. La pagina Ottieni una chiave API spiega registrazione e pannello account. /v1/status non richiede chiave o crediti, ma conferma soltanto la risposta HTTP: non convalida chiave, saldo o salute del motore di ricerca. Gestisci 400 come parametri non validi, 401 come chiave mancante o non valida, 402 come saldo insufficiente e 429 come limite di frequenza.
Leggi i prezzi prima di concatenare richieste: un successo costa un credito, anche vuoto, a $1 per 1000 recuperi con ricarica pagata minima di $50. Le richieste non valide non addebitano saldo e gli errori a monte restituiscono la prenotazione. Se il client perde una risposta dopo un successo addebitato, un altro tentativo riuscito costa un altro credito. Un errore nel tuo trattamento locale non trasforma il successo remoto in rimborso.
