Autenticação e rotas
As consultas de recuperação usam GET em https://api.redditcollector.com. Envie X-API-Key: <chave> ou Authorization: Bearer <chave>; ambas as opções são válidas. Guarde o segredo no seu servidor. O painel da conta usa uma sessão com cookie Secure HttpOnly, independente dos cabeçalhos de autenticação exigidos para que o seu aplicativo recupere dados do arquivo.
/v1/search pesquisa publicações e comentários, enquanto /v1/posts restringe a seleção a publicações e /v1/comments a comentários. Essas três rotas não aceitam id como filtro. Para um identificador conhecido, /v1/item?id=... consulta um registro individual. A operação não recupera automaticamente os comentários filhos, a cadeia de antecessores nem todos os registros de uma discussão.
/v1/subreddits admite prefix e limit para descobrir comunidades. prefix não é um filtro das rotas de conteúdo, e as contagens de comunidades não são um censo global garantido. /v1/status é público e não cobra créditos. Sua declaração estática confirma apenas que o aplicativo HTTP responde, sem testar o mecanismo de busca ou a disponibilidade dos registros.
Filtros e dados devolvidos
Os parâmetros de search, posts e comments são q, subreddit, author, kind, from, to, min_score, limit e page. kind aceita os valores literais post e comment. q faz busca textual, sem executar uma linguagem arbitrária de consultas e sem classificar sentimentos. A escolha de filtros precisa considerar que um comentário relevante pode depender de outro texto excluído pela seleção.
from e to usam YYYY-MM-DD em UTC e filtram created_utc. O dia indicado em to é incluído por inteiro. Esses parâmetros não recebem horários ou segundos e não representam a data de inclusão no arquivo. Registre o horário de recuperação separadamente no seu próprio protocolo de coleta.
As respostas são registros planos, sem árvores de encadeamento construídas pelo servidor. Os campos parent_id e link_id podem estar presentes para agrupamento local do cliente, mas não há filtros de consulta expostos para link_id ou parent_id. A resposta contém data, pagination e credits. Os campos individuais podem faltar e referências podem apontar para registros não recebidos. A associação local não garante uma conversa completa.
O filtro min_score atua exclusivamente como um filtro de recorte, nunca como um controle de classificação de pontuação. Ele exclui registros abaixo do valor especificado, mas não ordena os resultados por relevância ou popularidade. Isso não avalia a qualidade científica de uma publicação. Se usar esse critério, explique no protocolo quais registros ele pode excluir e por que a restrição faz sentido para sua pergunta.
Limites e tratamento de falhas
Em /v1/search, /v1/posts e /v1/comments, limit e page aceitam valores de 1 a 100, com uma página por solicitação. A entrega segue _doc, uma ordem interna, sem cronologia, relevância, pontuação ou amostragem aleatória garantida. /v1/subreddits aceita apenas prefix e limit, sem page. Ordenar localmente ou dividir períodos não comprova cobertura completa, unicidade ou estabilidade entre consultas.
Leia pagination.total junto com relation. eq indica um total exato para a consulta; gte informa um limite inferior; unknown indica que não há total confiável, possivelmente null. Nenhuma dessas relações comprova a presença de toda a história da comunidade. Mesmo um total exato não demonstra que você baixou todos os resultados. Preserve também os indicadores de paginação retornados.
HTTP 400 indica parâmetros inválidos, 401 uma chave ausente ou inválida, 402 saldo insuficiente e 429 limite de frequência. Cada recuperação bem-sucedida custa um crédito, mesmo vazia. Solicitações inválidas não descontam saldo; falhas do serviço de origem devolvem a reserva. Perder a resposta no cliente pode ocultar um sucesso cobrado. Uma nova tentativa bem-sucedida consome outro crédito; grave a resposta antes de avançar seu controle local.
