Structure des routes et limites de requête
L'API propose des points de terminaison distincts pour chaque type de contenu, notamment /v1/search, /v1/posts, /v1/comments, /v1/item, /v1/subreddits et /v1/status. Chaque route est conçue pour une utilisation précise dans l'analyse des données archivées sans nécessiter de complexité supplémentaire. Cette structure permet une navigation claire pour les analystes qui recherchent des données spécifiques.
Chaque requête est soumise à une limite stricte de cent enregistrements par demande et de cent pages par interrogation. Cela garantit que la charge serveur reste gérable tout en permettant une récupération efficace des données nécessaires. Les utilisateurs doivent gérer la pagination manuellement pour obtenir des ensembles de résultats plus vastes.
Le point de terminaison /v1/status renvoie une divulgation statique indiquant que le serveur HTTP répond correctement. Il ne vérifie pas la santé du moteur de recherche, ni la disponibilité des enregistrements ou la couverture des données. Cette absence de garantie opérationnelle signifie que le statut est public et non facturé.
Filtres de requête et sémantique des données
Les filtres disponibles incluent le terme de recherche, le subreddit, l'auteur, le type de contenu, les dates ISO et le score minimum. Le paramètre de type accepte uniquement les valeurs post et comment. Les paramètres de limite et de page permettent de contrôler le volume des données retournées, assurant ainsi une gestion fine des ressources récupérées lors des appels API.
Le filtre min_score agit exclusivement comme un filtre, jamais comme un contrôle de tri. L'ordre de récupération suit l'ordre _doc de l'archive, qui n'est ni chronologique ni basé sur la pertinence ou le score. Cette approche signifie que l'ordre des résultats dépend de l'indexation interne plutôt que d'une logique hiérarchique visible par l'utilisateur.
Seul le point de terminaison /v1/item nécessite un identifiant. Les routes /v1/posts et /v1/comments fonctionnent sans id. Les filtres par parent_id et link_id ne sont pas exposés pour les requêtes. Les clients peuvent regrouper localement les champs parent_id et link_id présents, mais il n'y a aucune promesse de complétude ou d'arbre complet.
Codes d'erreur et structure des réponses
Le code 400 indique une requête invalide, tandis que le 401 signale une clé manquante ou incorrecte. Le code 402 apparaît lorsqu'il y a un solde de crédit insuffisant pour compléter la demande. Le code 429 signale une limite de débit atteinte. Ces codes sont exprimés sous forme de chiffres ASCII littéraux pour une compatibilité universelle.
Les réponses de l'API contiennent des enregistrements plats, et non des arbres de discussion assemblés par le serveur. Lorsqu'un client reçoit des données, il peut les regrouper selon ses propres critères, mais l'API ne garantit pas l'exhaustivité des ancêtres ou des conversations complètes. Cette approche flat simplifie le traitement des données brutes.
Chaque récupération réussie coûte un crédit, même si la réponse est vide. Une requête invalide ne débite pas le solde ; un échec du service source restitue le crédit réservé. Une perte de réponse côté client peut toutefois survenir après une réussite déjà facturée. Une nouvelle tentative réussie coûte un autre crédit. Une erreur de traitement dans votre programme après réception ne rembourse pas non plus l’appel réussi. Le point de terminaison /v1/status est public et non facturé.
