Design wechseln
Sprache
German English Spanish French Japanese Korean Russian Chinese (Simplified)

API-Dokumentation

Integrationsregeln der Plattform-API

Eine kompakte Integrationsreferenz: API-Schlüssel korrekt senden, Antwortstruktur wählen, erste Anfrage stellen, Fehler behandeln und Testdaten prüfen.

API-Referenz V2 Plattformen API-Referenz V1
Wo Sie anfangen

Was diese Seite festlegt

Diese Seite bündelt die Regeln, die nicht von einer bestimmten API-Methode abhängen: Authentifizierung, Antwortversion, Fehlerbehandlung, Wiederholungen, Nutzung der Test-API und Start-Checks.

Nutzen Sie die API-Referenz für methodenspezifische Parameter, Schemas und Beispiele. Nutzen Sie die Plattformseiten, um Abdeckung und Methodengruppen zu vergleichen.

Betrachten Sie diese Seite als Team-Grundlage für neue Integrationen. Sie ergänzt die API-Referenz, statt sie zu wiederholen.
Ein Schlüssel pro Anfrage

Authentifizierung

Senden Sie Ihren API-Schlüssel bei jeder Anfrage an die Plattform-API im Header `X-API-Key`.

Der Schlüssel wird nicht aus einer Dashboard-Sitzung übernommen. Backend-Dienste, Worker und Hintergrundaufträge müssen diesen Header ausdrücklich mitsenden.

  • Bewahren Sie den Schlüssel in einem Secret Store auf und rotieren Sie ihn, wenn sich der Zugriff ändert oder Sie eine Offenlegung vermuten.
  • Legen Sie den Schlüssel nicht in Browser-Code, öffentlichen Repositories, Client-Bundles oder Protokollen ab.
  • Beschränken Sie den Zugriff auf den Schlüssel nach Möglichkeit pro Umgebung und pro Dienst.
Antwortversion

Wählen Sie eine Antwortstruktur

V1 und V2 bieten denselben Katalog an API-Methoden, liefern aber unterschiedliche Datenstrukturen. Wählen Sie die Version, bevor Sie den Client bauen, und legen Sie sie in der Integrationskonfiguration fest.

Mischen Sie V1 und V2 nicht im selben Verarbeitungsablauf. Das erschwert Mapping, Caching, Tests und Wartung.

V1
Ursprüngliche Antwort V1

Behält die Form der Antwort der Quellplattform mit minimalen Änderungen durch ScrapeStorm bei.

Verwenden, wenn

Migrationen, Abwärtskompatibilität und Clients, die bereits von den nativen Feldern der Plattform abhängen.

V2
Normalisierte Antwort V2

Bietet einen stabileren Datenvertrag für Produktcode, Analysen und interne Dienste.

Verwenden, wenn

Neue Integrationen, neue Dienste und jeder Code, der die Datenform der Quellplattform nicht benötigt.

Verwenden Sie standardmäßig V2. Behalten Sie V1 nur aus Kompatibilitätsgründen oder zur Migration bestehender Clients.
Transportprüfung

Stellen Sie Ihre erste echte API-Anfrage

Prüfen Sie nach der Wahl der Version die Integration mit einer Live-API-Methode: Basis-URL, Header, Query-Parameter, Timeout und Fehlerbehandlung.

HTTP-Methode GET
Endpunkt /api/v2/youtube.com/profile/about-by-user-identifier
Beispiel für einen Query-Parameter user_identifier=mkbhd
Header X-API-Key

Dieses Beispiel verwendet die YouTube-API-Methode `profile/about-by-user-identifier`. Ersetzen Sie `user_identifier` durch eine Testkennung aus Ihrem eigenen Szenario.

Eine erfolgreiche Antwort beweist nur, dass der Transport und die oberste Struktur funktionieren. Prüfen Sie jede API-Methode, die Sie starten wollen, zusammen mit Limits, Preisen und Fehlerbehandlung.
Antwort-Hülle

Prüfen Sie die Form der Antwort

Öffentliche Methoden der Plattform-API in V1 und V2 verwenden dieselbe äußere Hülle: `success`, `status` und `data`. Sammlungsmethoden können auf oberster Ebene zusätzlich `pagination` enthalten.

Die Wahl der Version ändert das Schema innerhalb von `data`, nicht die Transporthülle. Die genauen Felder der gewählten Methode finden Sie in der API-Referenz.

Antwortfall Felder der obersten Ebene Was zuerst zu lesen ist
Erfolgreiche Antwort success, status, data `data` enthält die Daten der Methode.
Erfolgreiche paginierte Antwort success, status, pagination, data `pagination` steht auf oberster Ebene; die Daten der Methode bleiben in `data`.
Fehlerantwort success, status, error, meta Verzweigen Sie nach HTTP-Status und `error.code`.
Leiten Sie V1 oder V2 nicht aus der Hülle ab. Legen Sie die Version in der URL und in der Client-Konfiguration fest und interpretieren Sie das Schema der Methode dann nach der Referenz dieser Version.
Fehler und Wiederholungen

Behandeln Sie Fehler nach Code, nicht nach Text

Fehler verwenden eine gemeinsame Hülle. Verzweigen Sie nach HTTP-Status und `error.code`. Das Feld `message` dient der Anzeige oder Protokollierung, nicht der Steuerung des Anwendungsablaufs.

  • `401`, `402` und `422` sollten nicht wiederholt werden, bis sich die Ursache ändert.
  • `429 RATE_LIMIT_EXCEEDED` sollte erst nach `Retry-After` oder `error.retry_after_seconds` wiederholt werden.
  • `500` und `503` sollten mit begrenztem Backoff und einer festen Obergrenze an Versuchen wiederholt werden.
HTTP-Status Fehlercode Aktion des Clients
401 Nicht autorisiert UNAUTHORIZED Prüfen Sie API-Schlüssel und Umgebung. Wiederholen Sie dieselbe Anfrage mit demselben Schlüssel nicht in einer Schleife.
422 Validierung fehlgeschlagen VALIDATION_FAILED Korrigieren Sie die Anfrageparameter. Dieselbe Eingabe liefert denselben Fehler.
402 Nicht genügend Credits INSUFFICIENT_CREDITS Stoppen Sie den Ablauf, bis Guthaben oder Kontolimits aktualisiert sind.
429 Gleichzeitige Verbindungen überschritten CONCURRENT_CONNECTIONS_EXCEEDED Reduzieren Sie die parallele Arbeit pro API-Schlüssel oder stellen Sie Anfragen in eine Warteschlange.
429 Rate Limit überschritten RATE_LIMIT_EXCEEDED Warten Sie das angegebene Wiederholungsintervall ab und koordinieren Sie Wiederholungen zwischen den Workern.
503 Endpunkt nicht verfügbar ENDPOINT_UNAVAILABLE Wenden Sie Backoff auf Methodenebene an, statt die gesamte Integration anzuhalten, wenn die anderen Methoden funktionieren.
500 Interner Serverfehler INTERNAL_SERVER_ERROR Wiederholen Sie mit begrenztem Backoff. Nach Erreichen der Versuchsgrenze protokollieren Sie den Fehler und eskalieren ihn über das Monitoring.
Für `RATE_LIMIT_EXCEEDED` ist die einzige verlässliche Quelle für den Zeitpunkt des nächsten Versuchs `Retry-After` oder `error.retry_after_seconds`.
Test-API

Prüfen Sie die Form mit Testdaten

Methoden der Test-API liefern statische JSON-Beispiele, ohne die Quellplattformen aufzurufen. Nutzen Sie sie für die Entwicklung des Clients, der Oberfläche und der Parser-Tests.

Die Test-API belegt weder Verfügbarkeit der Methode, Aktualität der Daten, Limits, Preise noch das Verhalten in Produktion. Wiederholen Sie dasselbe Szenario vor dem Start gegen die Live-API.
  • Verwenden Sie Testdaten nicht, um die Aktualität der Daten zu prüfen.
  • Übernehmen Sie keine Testwerte in die Logik der Live-Integration.
  • Vergleichen Sie nur die Hülle, die Feldnamen und die Grundstruktur der Antwort.
Test-API https://www.scrapestorm.net/api-mock
Beispiel https://www.scrapestorm.net/api-mock/v2/youtube.com/profile/about-by-user-identifier?user_identifier=mkbhd
API-Referenz
Referenz der Test-API V2 Referenz der Test-API V1
Vor dem Start

Checkliste für die Produktion

Gehen Sie diese Prüfungen vor echtem Traffic und vor dem Erhöhen der Worker-Parallelität durch.

  1. 01

    Die Antwortversion ist festgelegt

    Neue Clients verwenden V2. V1 ist nur aus Kompatibilitätsgründen oder zur Migration einer bestehenden Integration erlaubt.

  2. 02

    Der API-Schlüssel wird als Secret gespeichert

    Der Schlüssel liegt in einem Secret Store und bleibt außerhalb von Frontend-Code, öffentlichen Repositories, Client-Bundles und Protokollen.

  3. 03

    Die Fehlerbehandlung basiert auf maschinenlesbaren Codes

    Die Verzweigungen im Client hängen vom HTTP-Status und von `error.code` ab. `message` wird nicht in der Geschäftslogik verwendet.

  4. 04

    Wiederholungen sind begrenzt

    `RATE_LIMIT_EXCEEDED` wartet auf `Retry-After` oder `error.retry_after_seconds`. `402` und `422` werden mit derselben Eingabe nicht wiederholt. `500` und `503` haben Backoff und eine Versuchsgrenze.

  5. 05

    Die Parallelität wird pro API-Schlüssel gesteuert

    Eine Warteschlange oder ein Rate Limiter begrenzt gleichzeitige Anfragen von Workern, Cron-Jobs und Hintergrundprozessen.

  6. 06

    Test und Produktion werden getrennt geprüft

    Testdaten prüfen die Form der Daten. Die Live-API prüft echte Parameter, Limits, Verfügbarkeit und Credit-Verbrauch.

  7. 07

    Die Preise der API-Methoden sind bestätigt

    Prüfen Sie die Kosten der API-Methoden, die Sie nutzen werden, bevor der Traffic steigt.