Descubrir nombres y buscar contenido son tareas distintas
Empieza por definir la unidad que necesita tu aplicación. Si es un nombre de comunidad para un selector o catálogo local, /v1/subreddits ofrece descubrimiento por prefijo. Si es texto de publicaciones y comentarios, necesitas una ruta de contenido. El archivo es histórico e independiente, no una conexión oficial o en directo con Reddit. Documenta esta diferencia en tu interfaz para no presentar un catálogo parcial como la lista actual de todas las comunidades.
Prueba https://api.redditapihub.com/v1/subreddits?prefix=program&limit=3, el ejemplo de la página de inicio. prefix selecciona nombres que comienzan por program y limit pide como máximo tres entradas. Solo están admitidos prefix y limit; no añadas page, q o subreddit. Guarda los nombres realmente recibidos. count no garantiza un recuento global exacto y relation=unknown con total=null no demuestra que falten cero comunidades.
Cuando un usuario elija un nombre recibido, tu aplicación puede enviarlo como filtro subreddit a /v1/search. Esa es una nueva recuperación, no una continuación automática del catálogo ni una promesa de contexto completo. q busca texto y no nombres de comunidades. Ni encontrar programming en el catálogo ni recibir registros de ese subreddit demuestra la presencia de todas sus publicaciones o comentarios históricos.
Elegir el tipo de registro sin inventar jerarquías
Usa /v1/search si interesan ambos tipos de contenido. /v1/posts añade una restricción a publicaciones y /v1/comments a comentarios. No elijas entre estas rutas suponiendo que search solo contiene resúmenes y posts devuelve una versión completa: esa diferencia de proyección no forma parte del contrato. Las respuestas incluyen los campos archivados disponibles, que pueden variar. Conserva los campos ausentes como tales en lugar de rellenarlos con supuestos.
Cuando conozcas un identificador, /v1/item?id=... busca ese registro individual y exige id. Las rutas de búsqueda no admiten id como filtro. La consulta puntual no recupera automáticamente respuestas, ancestros ni un hilo completo, y el registro puede no estar disponible. Un campo parent_id o link_id presente permite intentar una asociación local entre datos recibidos; no crea un filtro adicional ni demuestra que todos los participantes estén representados.
Para search, posts y comments, elige entre q, subreddit, author, kind, from, to, min_score, limit y page. kind conserva los literales post y comment. from/to usan YYYY-MM-DD y filtran created_utc en UTC, incluyendo el día final completo. min_score aplica un umbral sin ordenar. La entrega usa _doc, no cronología, relevancia o puntuación. Si ordenas localmente, solo estás reorganizando los registros recibidos.
Validar el resultado y presupuestar el recorrido
En las rutas de contenido limit y page van de 1 a 100; cada solicitud obtiene una página. Interpreta eq como total exacto de la consulta, gte como cota inferior y unknown como ausencia de un total fiable. Ni el total exacto, ni recorrer páginas o dividir fechas prueba una descarga exhaustiva. Conserva la respuesta y sus límites antes de avanzar tu progreso local. Consulta la documentación para comprobar los parámetros de cada ruta.
Para las recuperaciones protegidas usa X-API-Key: <clave> o Authorization: Bearer <clave> y guarda la clave en tu servidor. Obtener clave API explica el registro y su panel de cuenta. /v1/status no exige clave ni cobra, pero solo confirma que responde la aplicación HTTP: no valida credenciales, saldo ni salud del buscador. Trata 400 como parámetros inválidos, 401 como clave ausente o inválida, 402 como saldo insuficiente y 429 como límite de frecuencia.
Consulta los precios antes de diseñar cadenas de solicitudes: un éxito cuesta un crédito, incluso vacío, a $1 por 1000 recuperaciones y con recarga pagada mínima de $50. Las solicitudes inválidas no descuentan saldo y un fallo del origen devuelve la reserva. Si el cliente pierde una respuesta después de un éxito cobrado, otra tentativa exitosa cuesta otro crédito. Un fallo en tu procesamiento local no convierte la recuperación remota en un reembolso.
