Distinguer découverte des noms et recherche de contenu
Commencez par définir l’unité attendue par votre application. Pour un nom de communauté dans un sélecteur ou un catalogue local, /v1/subreddits propose une découverte par préfixe. Pour le texte de publications et de commentaires, choisissez une route de contenu. L’archive est historique et indépendante, sans connexion officielle ou en direct à Reddit. Rendez cette distinction visible pour éviter qu’un catalogue partiel soit présenté comme la liste actuelle de toutes les communautés.
Essayez https://api.redditapihub.com/v1/subreddits?prefix=program&limit=3, l’exemple de l’accueil. prefix sélectionne les noms commençant par program et limit demande au maximum trois entrées. Seuls prefix et limit sont acceptés : n’ajoutez ni page, ni q, ni subreddit. Conservez les noms réellement reçus. count ne garantit pas un décompte global exact et relation=unknown avec total=null ne signifie pas qu’aucune communauté ne manque dans la liste.
Lorsqu’un nom reçu est sélectionné, votre application peut le transmettre comme filtre subreddit à /v1/search. C’est une nouvelle récupération, sans prolongement automatique du catalogue ni promesse de contexte complet. q recherche du texte, pas des noms de communautés. Trouver programming dans le catalogue ou recevoir des enregistrements de cette communauté ne prouve pas que toutes ses publications et tous ses commentaires historiques soient disponibles.
Choisir un type d’enregistrement sans inventer de hiérarchie
Utilisez /v1/search si les deux types de contenu vous intéressent. /v1/posts ajoute une restriction aux publications et /v1/comments aux commentaires. Ne supposez pas que search livre seulement des résumés et posts une version complète : cette différence de projection ne fait pas partie du contrat. Les routes renvoient les champs archivés disponibles, dont la présence peut varier. Conservez les absences comme telles au lieu de les combler par des valeurs supposées.
Pour un identifiant connu, /v1/item?id=... cherche un seul enregistrement et exige id. Les routes de recherche n’acceptent pas id comme filtre. Cette consultation ne parcourt pas automatiquement les réponses ou les ancêtres et l’enregistrement demandé peut manquer. Un champ parent_id ou link_id présent permet une association locale entre les données reçues ; il ne crée pas de filtre supplémentaire et ne prouve pas que toute la discussion est représentée.
Pour search, posts et comments, les paramètres sont q, subreddit, author, kind, from, to, min_score, limit et page. kind conserve les valeurs littérales post et comment. from/to utilisent YYYY-MM-DD et filtrent created_utc en UTC, avec toute la journée finale incluse. min_score applique un seuil sans trier. La livraison suit _doc, sans classement par chronologie, pertinence ou score. Un tri local réorganise uniquement les enregistrements déjà reçus.
Valider la réponse et prévoir le coût du parcours
Sur les routes de contenu, limit et page vont de 1 à 100 ; une requête reçoit une page. Interprétez eq comme un total exact pour la requête, gte comme une borne inférieure et unknown comme l’absence de total fiable. Ni un total exact, ni les pages parcourues ou les dates divisées ne prouvent un téléchargement exhaustif. Conservez la réponse et ses limites avant d’avancer votre progression locale. La documentation détaille les paramètres acceptés par chaque route.
Pour les récupérations protégées, utilisez X-API-Key: <clé> ou Authorization: Bearer <clé> et gardez le secret sur votre serveur. La page Obtenir une clé API explique inscription et panneau du compte. /v1/status ne demande ni clé ni crédit, mais confirme seulement la réponse HTTP : il ne valide ni clé, ni solde, ni santé du moteur de recherche. Traitez 400 comme des paramètres invalides, 401 comme une clé absente ou invalide, 402 comme un solde insuffisant et 429 comme une limite de fréquence.
Lisez les tarifs avant d’enchaîner des requêtes : une réussite coûte un crédit, même vide, à $1 pour 1000 récupérations avec un achat minimal de $50. Les requêtes invalides ne débitent pas le solde et les échecs du service source restituent la réservation. Si le client perd une réponse après une réussite facturée, un autre essai réussi coûte un autre crédit. Une erreur dans votre traitement local ne transforme pas le succès distant en remboursement.
