Autenticazione e percorsi disponibili
I percorsi di recupero usano GET su https://api.redditfetch.com. Invia X-API-Key: <chiave> oppure Authorization: Bearer <chiave>; entrambi gli header sono validi. Conserva il segreto sul tuo server. Il pannello account usa una sessione con cookie Secure HttpOnly, distinta dall’autenticazione delle richieste di dati. La sessione del pannello non sostituisce l’header necessario nel client della tua applicazione.
/v1/search cerca pubblicazioni e commenti; /v1/posts limita i risultati alle pubblicazioni e /v1/comments ai commenti. Questi percorsi non accettano id come filtro. Per un identificatore noto usa /v1/item?id=..., che cerca un singolo record. Non recupera automaticamente le risposte, tutti i discendenti o la catena dei commenti precedenti e non garantisce che il record cercato sia disponibile.
/v1/subreddits accetta prefix e limit per scoprire comunità. prefix non è un filtro dei percorsi di contenuto. I conteggi delle comunità non sono un censimento globale garantito. /v1/status è pubblico e non addebita crediti: restituisce una descrizione statica del servizio e conferma la risposta dell’applicazione HTTP, senza verificare il motore di ricerca né la disponibilità dei record archiviati.
Filtri e struttura della risposta
I parametri di search, posts e comments sono q, subreddit, author, kind, from, to, min_score, limit e page. kind accetta i valori letterali post e comment. q esegue una ricerca testuale, non un linguaggio arbitrario di query e non un’analisi del sentiment. Scegli i filtri considerando quali messaggi potrebbero escludere proprio quando servono a comprendere il contesto di una risposta.
from e to usano YYYY-MM-DD in UTC e si applicano a created_utc. Il giorno indicato da to è incluso per intero. Questi parametri non ricevono ore o secondi e non rappresentano il momento di ingresso nell’archivio. min_score è una soglia numerica di punteggio: non ordina i risultati e non riconosce automaticamente i consigli più utili o gli autori più affidabili.
Una risposta di recupero contiene data, pagination e credits. I documenti in data sono piatti e i campi disponibili possono variare. Quando parent_id e link_id sono presenti, puoi raggruppare i riferimenti localmente; non esistono filtri di query per questi campi. Conserva testo assente e riferimenti irrisolti invece di presumere che ogni commento includa tutti gli identificatori o una catena completa di antecedenti.
Paginazione, errori e addebiti
limit e page accettano valori da 1 a 100. L’ordine interno _doc non garantisce un ordinamento cronologico, per pertinenza o per punteggio. Una tabella ordinata localmente riorganizza solo ciò che hai ricevuto. Suddividere le date o percorrere le pagine può organizzare la raccolta, senza dimostrare completezza, unicità dei record o stabilità tra richieste remote successive.
I totali della paginazione forniscono informazioni sulla precisione dei risultati. Un valore uguale indica un conteggio esatto, maggiore o uguale indica un limite inferiore e sconosciuto significa che non esiste un totale affidabile. Questi valori non devono essere interpretati come una garanzia di copertura completa dell'archivio. Gli sviluppatori devono gestire queste incertezze nella logica di iterazione per evitare cicli infiniti o attese errate. Leggi i valori letterali relation: eq significa totale esatto della query, gte limite inferiore e unknown totale non affidabile, eventualmente null. Sconosciuto non significa zero; anche un totale esatto non dimostra che tutti i risultati siano stati scaricati.
HTTP 400 indica parametri non validi, 401 una chiave mancante o non valida, 402 saldo insufficiente e 429 un limite di frequenza. Un recupero riuscito costa un credito, anche vuoto. Le richieste non valide non addebitano il saldo; gli errori del servizio a monte restituiscono la riserva. La perdita della risposta nel client può seguire un successo addebitato. Un nuovo tentativo riuscito costa un altro credito; salva le risposte prima di aggiornare l’avanzamento locale.
