Come recuperare record dall’archivio storico

Rotte GET, autenticazione, filtri consentiti, paginazione e codici HTTP. Leggi il contratto di recupero prima di trasformare i campi.

Ottieni una chiave API

Endpoint e parametri consentiti

Le richieste di lettura usano GET. Invia la chiave di questo dominio con Authorization: Bearer oppure X-API-Key. /v1/search cerca contenuti, mentre /v1/posts impone il tipo post e /v1/comments il tipo comment. Questi ultimi due endpoint non richiedono id. /v1/item richiede id per un singolo elemento e non accetta i filtri generali di una ricerca di contenuti.

Le ricerche di contenuti accettano q, subreddit, author, kind, from, to, min_score, limit e page. kind può essere post o comment. Le date from e to hanno formato YYYY-MM-DD e filtrano created_utc in UTC; to comprende l’intera giornata finale. min_score è una soglia, non un criterio di ordinamento. Non sono disponibili filtri di ricerca per parent_id o link_id.

/v1/subreddits consente di cercare nomi con prefix e limit. Non accetta page né i filtri temporali delle ricerche di contenuti, e i suoi conteggi non sono un inventario globale esatto. /v1/status è pubblico e non addebitato. Restituisce una dichiarazione statica e conferma che il server HTTP risponde, senza controllare il motore di ricerca o la disponibilità di specifici record.

Pagine e significato dei risultati

Nelle ricerche di contenuti, limit e page vanno da 1 a 100. L’ordine _doc è interno all’archivio, non cronologico, per rilevanza o per punteggio. Percorrere tutte le pagine consentite non dimostra un recupero esaustivo. Restringere l’intervallo di date può delimitare il lavoro, ma non prova che tutti i record di quel periodo siano disponibili o siano stati estratti.

Interpreta il totale insieme alla sua relazione: eq indica un valore esatto, gte un limite inferiore e unknown l’assenza di un totale affidabile, che può essere null. Non trasformare unknown in zero. Conserva queste indicazioni accanto ai parametri della richiesta per distinguere il numero di righe osservate dal numero di elementi che non puoi quantificare con certezza.

I record sono piatti. Esamina presenza e tipo dei campi prima di inserirli nel modello di destinazione. I riferimenti parent_id e link_id, quando disponibili, permettono collegamenti locali senza garantire una conversazione completa. Un requisito del tuo database, come un titolo obbligatorio, non diventa una proprietà garantita della risposta: gestisci la differenza nel tuo convertitore.

Errori e addebito dei crediti

HTTP 400 indica una richiesta non valida: controlla nomi, valori e formati dei parametri. HTTP 401 segnala una chiave assente o non valida, HTTP 402 un saldo insufficiente e HTTP 429 il limite di frequenza. Correggi la causa prima di riprovare. Un errore 401 non impone sempre di rigenerare la chiave: verifica anche intestazione e dominio di appartenenza.

Ogni recupero riuscito consuma un credito, anche vuoto. Le richieste rifiutate non consumano crediti e un errore del servizio di origine restituisce la prenotazione. Se il client perde una risposta dopo il successo del server, il recupero può essere stato addebitato. Un nuovo tentativo riuscito costa un altro credito. Un errore nella normalizzazione locale non annulla un recupero già riuscito.

Percorsi API

Metodo	Percorso	Parametri
`GET`	`/v1/search`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/posts`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/comments`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/item`	`id`
`GET`	`/v1/subreddits`	`prefix, limit`
`GET`	`/v1/status`	`—`

Parametri di ricerca

Parametro	Valore / tipo / intervallo
`q`	`text`
`subreddit`	`keyword`
`author`	`keyword`
`kind`	`post \| comment`
`from`	`ISO date`
`to`	`ISO date`
`min_score`	`integer`
`limit`	`1–100`
`page`	`1–100`
`id`	`item ID`
`prefix`	`subreddit prefix`