Changer de thème
Langue
German English Spanish French Japanese Korean Russian Chinese (Simplified)

Documentation de l'API

Règles d'intégration de l'API de plateformes

Une référence d'intégration concise : envoyer correctement la clé API, choisir la structure de réponse, effectuer la première requête, gérer les erreurs et valider les données de test.

Référence de l'API V2 Plateformes Référence de l'API V1
Par où commencer

Ce que fixe cette page

Cette page réunit les règles qui ne dépendent pas d'une méthode d'API précise : authentification, version de la réponse, gestion des erreurs, nouvelles tentatives, utilisation de l'API de test et vérifications de lancement.

Utilisez la référence de l'API pour les paramètres, schémas et exemples propres à chaque méthode. Utilisez les pages des plateformes pour comparer la couverture et les groupes de méthodes.

Considérez cette page comme la base commune de l'équipe pour les nouvelles intégrations. Elle complète la référence de l'API au lieu de la répéter.
Une clé par requête

Authentification

Envoyez votre clé API dans l'en-tête `X-API-Key` à chaque requête vers l'API de plateformes.

La clé n'est pas reprise d'une session du tableau de bord. Les services backend, les workers et les tâches en arrière-plan doivent envoyer cet en-tête explicitement.

  • Conservez la clé dans un gestionnaire de secrets et renouvelez-la lorsque les accès changent ou si vous soupçonnez une fuite.
  • Ne placez pas la clé dans du code navigateur, des dépôts publics, des bundles clients ou des journaux.
  • Limitez si possible l'accès à la clé par environnement et par service.
Version de la réponse

Choisissez une structure de réponse

V1 et V2 proposent le même catalogue de méthodes d'API mais renvoient des structures de données différentes. Choisissez la version avant de construire le client et fixez-la dans la configuration de l'intégration.

Ne mélangez pas V1 et V2 dans le même flux de traitement. Cela complique le mapping, la mise en cache, les tests et la maintenance.

V1
Réponse d'origine V1

Conserve la forme de la réponse de la plateforme source avec un minimum de modifications par ScrapeStorm.

À utiliser quand

Migrations, rétrocompatibilité et clients qui dépendent déjà des champs natifs de la plateforme.

V2
Réponse normalisée V2

Fournit un contrat de données plus stable pour le code produit, l'analyse et les services internes.

À utiliser quand

Nouvelles intégrations, nouveaux services et tout code qui n'a pas besoin de la forme des données de la plateforme source.

Utilisez V2 par défaut. Ne conservez V1 que pour la compatibilité ou la migration de clients existants.
Vérification du transport

Effectuez votre première requête réelle à l'API

Une fois la version choisie, vérifiez l'intégration avec une méthode de l'API en direct : URL de base, en-têtes, paramètres de requête, délai d'expiration et gestion des erreurs.

Méthode HTTP GET
Endpoint /api/v2/youtube.com/profile/about-by-user-identifier
Exemple de paramètre de requête user_identifier=mkbhd
En-tête X-API-Key

Cet exemple utilise la méthode d'API YouTube `profile/about-by-user-identifier`. Remplacez `user_identifier` par un identifiant de test issu de votre propre scénario.

Une réponse réussie prouve seulement que le transport et la structure de premier niveau fonctionnent. Validez chaque méthode d'API que vous comptez lancer, avec ses limites, ses prix et sa gestion des erreurs.
Enveloppe de réponse

Vérifiez la forme de la réponse

Les méthodes publiques de l'API de plateformes en V1 et V2 utilisent la même enveloppe externe : `success`, `status` et `data`. Les méthodes de collection peuvent aussi inclure `pagination` au premier niveau.

Le choix de la version modifie le schéma à l'intérieur de `data`, pas l'enveloppe de transport. Consultez la référence de l'API pour les champs exacts de la méthode choisie.

Cas de réponse Champs de premier niveau Ce qu'il faut lire en premier
Réponse réussie success, status, data `data` contient les données de la méthode.
Réponse paginée réussie success, status, pagination, data `pagination` est au premier niveau ; les données de la méthode restent dans `data`.
Réponse d'erreur success, status, error, meta Branchez selon le statut HTTP et `error.code`.
Ne déduisez pas V1 ou V2 de l'enveloppe. Fixez la version dans l'URL et dans la configuration du client, puis interprétez le schéma de la méthode selon la référence de cette version.
Erreurs et nouvelles tentatives

Gérez les erreurs par code, pas par texte

Les erreurs utilisent une enveloppe commune. Branchez selon le statut HTTP et `error.code`. Le champ `message` sert à l'affichage ou à la journalisation, pas au contrôle du flux applicatif.

  • `401`, `402` et `422` ne doivent pas être relancées tant que la cause n'a pas changé.
  • `429 RATE_LIMIT_EXCEEDED` ne doit être relancée qu'après `Retry-After` ou `error.retry_after_seconds`.
  • `500` et `503` doivent être relancées avec un backoff borné et un nombre maximal de tentatives.
Statut HTTP Code d'erreur Action du client
401 Non autorisé UNAUTHORIZED Vérifiez la clé API et l'environnement. Ne relancez pas la même requête avec la même clé en boucle.
422 Échec de la validation VALIDATION_FAILED Corrigez les paramètres de la requête. La même entrée renverra la même erreur.
402 Crédits insuffisants INSUFFICIENT_CREDITS Arrêtez le flux jusqu'à la mise à jour du solde ou des limites du compte.
429 Connexions simultanées dépassées CONCURRENT_CONNECTIONS_EXCEEDED Réduisez le travail parallèle par clé API ou placez les requêtes dans une file d'attente.
429 Limite de débit dépassée RATE_LIMIT_EXCEEDED Attendez l'intervalle de nouvelle tentative indiqué et coordonnez les nouvelles tentatives entre les workers.
503 Endpoint indisponible ENDPOINT_UNAVAILABLE Appliquez un backoff au niveau de la méthode plutôt que d'arrêter toute l'intégration si les autres méthodes fonctionnent.
500 Erreur interne du serveur INTERNAL_SERVER_ERROR Réessayez avec un backoff borné. Une fois la limite de tentatives atteinte, journalisez l'échec et remontez-le via la supervision.
Pour `RATE_LIMIT_EXCEEDED`, la seule source fiable pour le moment de la prochaine tentative est `Retry-After` ou `error.retry_after_seconds`.
API de test

Validez la forme avec des données de test

Les méthodes de l'API de test renvoient des exemples JSON statiques sans appeler les plateformes sources. Utilisez-les pour développer le client, l'interface et les tests des parseurs.

L'API de test ne prouve ni la disponibilité de la méthode, ni la fraîcheur des données, ni les limites, ni les prix, ni le comportement en production. Rejouez le même scénario sur l'API en direct avant le lancement.
  • N'utilisez pas les données de test pour vérifier la fraîcheur des données.
  • Ne reprenez pas les valeurs de test dans la logique de l'intégration en direct.
  • Comparez uniquement l'enveloppe, les noms des champs et la structure de base de la réponse.
API de test https://www.scrapestorm.net/api-mock
Exemple https://www.scrapestorm.net/api-mock/v2/youtube.com/profile/about-by-user-identifier?user_identifier=mkbhd
Référence de l'API
Référence de l'API de test V2 Référence de l'API de test V1
Avant le lancement

Liste de contrôle pour la production

Passez ces vérifications avant d'envoyer du trafic réel et d'augmenter le parallélisme des workers.

  1. 01

    La version de la réponse est fixée

    Les nouveaux clients utilisent V2. V1 n'est autorisée que pour la compatibilité ou la migration d'une intégration existante.

  2. 02

    La clé API est stockée comme un secret

    La clé est dans un gestionnaire de secrets et reste hors du code frontend, des dépôts publics, des bundles clients et des journaux.

  3. 03

    La gestion des erreurs repose sur des codes lisibles par machine

    Les branchements du client dépendent du statut HTTP et de `error.code`. `message` n'est pas utilisé dans la logique métier.

  4. 04

    Les nouvelles tentatives sont bornées

    `RATE_LIMIT_EXCEEDED` attend `Retry-After` ou `error.retry_after_seconds`. `402` et `422` ne sont pas relancées avec la même entrée. `500` et `503` ont un backoff et une limite de tentatives.

  5. 05

    Le parallélisme est contrôlé par clé API

    Une file d'attente ou un limiteur de débit borne les requêtes simultanées des workers, des tâches cron et des processus en arrière-plan.

  6. 06

    Le test et la production sont validés séparément

    Les données de test valident la forme des données. L'API en direct valide les paramètres réels, les limites, la disponibilité et la consommation de crédits.

  7. 07

    Les prix des méthodes d'API sont confirmés

    Vérifiez le coût des méthodes d'API que vous utiliserez avant que le trafic n'augmente.

Suite

Référence de l'API et plateformes

Ouvrez la version nécessaire de la référence de l'API pour les paramètres, schémas et exemples précis de chaque méthode. Utilisez Plateformes pour choisir la source et le groupe de méthodes.

En direct Référence de l'API V2 avec réponse normalisée En direct Référence de l'API V1 avec réponse d'origine Test Référence de l'API de test V2 avec exemples statiques Test Référence de l'API de test V1 avec exemples statiques Plateformes Plateformes prises en charge et groupes de méthodes d'API