Descobrir nomes e buscar conteúdo são tarefas diferentes
Comece pela unidade que seu aplicativo precisa receber. Se for um nome de comunidade para um seletor ou catálogo local, /v1/subreddits oferece descoberta por prefixo. Se for texto de publicações ou comentários, escolha uma rota de conteúdo. O serviço é um arquivo histórico independente, não uma conexão oficial ou ao vivo com o Reddit. Mostre essa diferença na interface para não apresentar um catálogo parcial como a lista atual de todas as comunidades.
Experimente https://api.redditapihub.com/v1/subreddits?prefix=program&limit=3, o exemplo da página inicial. prefix escolhe nomes que começam com program e limit pede até três entradas. Somente prefix e limit são aceitos; não acrescente page, q ou subreddit. Guarde os nomes realmente recebidos. count não garante uma contagem global exata, e relation=unknown com total=null não significa que nenhuma comunidade ficou fora da lista.
Quando alguém escolher um nome recebido, sua aplicação pode usá-lo como filtro subreddit em /v1/search. Isso é outra recuperação, não uma continuação automática do catálogo nem a promessa de contexto completo. q busca texto, não nomes de comunidades. Encontrar programming na lista ou receber registros desse subreddit não demonstra que todas as publicações e todos os comentários históricos estejam disponíveis no arquivo.
Escolher o tipo de registro sem inventar hierarquias
Use /v1/search quando ambos os tipos de conteúdo interessarem. /v1/posts acrescenta a restrição a publicações e /v1/comments a comentários. Não suponha que search entrega apenas resumos e posts uma versão completa: essa diferença de projeção não faz parte do contrato. As rotas devolvem os campos arquivados disponíveis, que podem variar. Preserve a ausência de um campo em vez de preencher sua estrutura com valores presumidos.
Para um identificador conhecido, /v1/item?id=... busca um registro individual e exige id. As rotas de busca não aceitam id como filtro. A consulta pontual não recupera automaticamente respostas, antecessores ou uma discussão inteira, e o registro procurado pode estar ausente. Um campo parent_id ou link_id presente permite tentar uma associação local entre registros recebidos; não cria outro filtro nem prova que todos os participantes estejam representados.
Em search, posts e comments, os parâmetros são q, subreddit, author, kind, from, to, min_score, limit e page. kind usa os valores literais post e comment. from/to seguem YYYY-MM-DD e filtram created_utc em UTC, incluindo o dia final inteiro. min_score aplica um limiar sem ordenar. A entrega segue _doc, não cronologia, relevância ou pontuação. Uma ordenação local reorganiza somente os registros que já chegaram.
Validar respostas e estimar o custo do percurso
Nas rotas de conteúdo, limit e page vão de 1 a 100; cada solicitação recebe uma página. Interprete eq como total exato da consulta, gte como limite inferior e unknown como ausência de total confiável. Nem um total exato, nem percorrer páginas ou dividir datas comprova download completo. Conserve a resposta e seus limites antes de avançar seu controle local. A documentação ajuda a conferir os parâmetros aceitos por cada rota.
Para recuperações protegidas, use X-API-Key: <chave> ou Authorization: Bearer <chave> e mantenha o segredo no servidor. A página Obter chave API explica cadastro e painel da conta. /v1/status não exige chave nem cobra, mas confirma somente que o aplicativo HTTP responde: não valida chave, saldo ou saúde do mecanismo de busca. Trate 400 como parâmetros inválidos, 401 como chave ausente ou inválida, 402 como saldo insuficiente e 429 como limite de frequência.
Leia os preços antes de encadear solicitações: um sucesso custa um crédito, inclusive vazio, a $1 por 1000 recuperações e com recarga paga mínima de $50. Pedidos inválidos não descontam saldo, e falhas do serviço de origem devolvem a reserva. Se o cliente perder uma resposta depois de um sucesso cobrado, outra tentativa bem-sucedida custa outro crédito. Uma falha no processamento local não transforma o sucesso remoto em reembolso.
