Autenticazione e percorsi disponibili
I percorsi di recupero usano GET su https://api.redditgateway.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 risultati più utili per la tua applicazione.
Il parametro min_score funge esclusivamente da filtro e non controlla l'ordinamento dei risultati. L'ordine dei documenti nell'archivio segue l'ordine interno _doc, che non è cronologico, né basato sulla rilevanza o sul punteggio. I client possono raggruppare localmente i campi parent_id e link_id presenti nei record piatti, ma non vi è alcuna garanzia di completezza. I campi dei singoli record possono mancare. La risposta comprende data, pagination e credits; un riferimento a un record assente non equivale al suo recupero. parent_id e link_id non sono filtri di ricerca esposti dal servizio.
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.
Leggi pagination.total insieme a relation: eq indica il totale esatto della query, gte un limite inferiore e unknown un totale non affidabile, eventualmente null. Non sostituire sconosciuto con zero. Anche un totale esatto non dimostra che tutti i risultati siano stati scaricati né che l’archivio contenga tutta la storia della comunità. Conserva anche gli indicatori di paginazione restituiti per documentare i limiti incontrati.
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.
