Autenticazione e percorsi disponibili
I percorsi di recupero usano GET su https://api.redditapilabs.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.
I dati restituiti sono record piatti e non alberi di thread assemblati dal server. Quando i campi parent_id e link_id sono presenti, il client può raggrupparli localmente per simulare le conversazioni. Non sono garantite né la catena completa dei genitori né la ricostruzione dell’intera cronologia delle discussioni. I campi possono mancare o riferirsi a record non ricevuti. La risposta contiene data, pagination e credits. parent_id e link_id non sono filtri di query. Separa i valori originali dalle annotazioni del protocollo.
Paginazione, errori e addebiti
Nei percorsi /v1/search, /v1/posts e /v1/comments, limit e page accettano valori da 1 a 100, con una pagina per richiesta. La consegna segue _doc, un ordine interno, senza cronologia, rilevanza, punteggio o campionamento casuale garantiti. /v1/subreddits accetta soltanto prefix e limit, senza page. Ordinare localmente o suddividere le date non dimostra completezza, unicità o stabilità tra richieste 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.
