Autenticazione e percorsi disponibili
I percorsi di recupero usano GET su https://api.redditapicloud.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 soltanto prefix e limit, senza page. Cerca prefissi dei nomi delle comunità, non temi nei contenuti, e i conteggi non sono un censimento globale esatto garantito. /v1/status è pubblico e gratuito: dichiara staticamente l’ambito e conferma la risposta HTTP senza verificare ricerca, chiave o saldo.
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 senza un albero di thread server. I campi parent_id e link_id sono opzionali. È possibile raggruppare i dati lato client per ricostruire conversazioni, ma non esiste una garanzia completa sulla struttura gerarchica delle discussioni originali. 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 ricerca.
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.
