Daten aus 84 APIs in ein einheitliches Schema normalisieren (mit Contract-Tests)

Normalisierung von Bewertungen aus 84 Plattformen – 59 mit offizieller API und 25 ohne: ein einheitliches Schema, stabile IDs, Deduplizierung und Vertragstests gegen eine OpenAPI-Spezifikation.

Francisco Garcia Domene

Francisco Garcia Domene

16 November 2026

Daten aus 84 APIs in ein einheitliches Schema normalisieren (mit Contract-Tests)

Apidog für Unternehmen

On-Premises Bereitstellung

SSO & RBAC

SOC 2 konform

Apidog Enterprise entdecken

Ich betreibe Prisma Reviews, eine kleine API, die Kundenbewertungen von 84 Plattformen in einem einzigen JSON-Format zurückgibt. Dieser Beitrag handelt nicht vom Produkt, sondern von drei technischen Problemen, die den Großteil unserer Zeit beansprucht haben: der Entwurf eines Schemas, das zu Quellen mit sehr unterschiedlichen Strukturen passt, stabile IDs, damit dieselbe Bewertung nie doppelt auftaucht, und das Testen des Vertrags, damit eine Änderung vorgelagert keine Clients downstream still und leise bricht.

Vorerst eine Sache, weil sie alles andere prägt: Nicht jede Bewertungsquelle ist eine API. Von unseren 84 Quellen haben 59 eine offizielle API. Die anderen 25 nicht, und wir lesen stattdessen ihre öffentlichen Seiten oder Feeds.

Nicht jede Quelle ist eine API

Jede Plattform in unserer Konfiguration hat drei Eigenschaften: wie ein Unternehmen sie verbindet, ob wir eine Antwort veröffentlichen können und wie neue Bewertungen zu uns gelangen. Sortiert man die 84 Quellen nach der Art, wie wir sie auslesen, ergeben sich vier Gruppen:

GruppeQuellenBeispiele
Offizielle API, eigene Zugangsdaten des Unternehmens oder OAuth50Google Business Profile (Zugang ausstehend), App Store, Google Play, Trustpilot (Zugang ausstehend), Judge.me, Yotpo, eBay, Wix, WooCommerce, Shopware, Property Manager wie Hostaway und Guesty
Offizielle öffentliche API, keine Zugangsdaten des Unternehmens9Steam, Etsy, Salesforce AppExchange, Atlassian Marketplace, VS Code Marketplace, Open VSX, JetBrains Marketplace, Thunderbird Add-ons, Viator
Keine API: öffentliche Seite oder Feed3Shopify App Store (HTML-Bewertungsseite), WordPress.org (RSS-Bewertungsfeed), Apple Podcasts (öffentlicher Bewertungsfeed)
Keine API: kostenpflichtiger Datenanbieter22Google Maps, Yelp, Tripadvisor, Booking.com, Facebook, Airbnb, Expedia, Capterra, OpenTable
Bar chart of 84 review sources: 50 with an official API using business credentials, 9 with a public API, 3 read from a public page or feed, 22 read through a paid data provider

Die Gruppen unterscheiden sich in punkten, die sich bis in das API-Design hineinziehen:

Manche Plattformen tauchen doppelt auf. Airbnb- und Booking.com-Bewertungen können von einer öffentlichen Seite stammen (nur lesend) oder über die offizielle API eines Property Managers kommen, die Antworten erlaubt. Genau dafür ist eines der Felder unten da.

Ein Schema für alle

Jede Bewertung, aus jeder Quelle, hat dieselben 14 Felder, und alle sind immer vorhanden. Wenn eine Plattform uns etwas nicht liefert, ist das Feld null, nie abwesend. Ein fehlender Schlüssel und ein null bedeuten für einen Menschen dasselbe, aber nicht für einen typisierten Client, und „immer vorhanden" lässt sich leicht testen.

{
  "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E",
  "platform": "google",
  "location_id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N",
  "rating": 4,
  "title": null,
  "text": "Great flat white, a bit slow at lunchtime.",
  "author": "Marta G.",
  "language": "en",
  "url": null,
  "source": null,
  "created_at": "2026-10-19T12:41:07.000Z",
  "updated_at": "2026-10-19T12:41:07.000Z",
  "deleted_at": null,
  "reply": null
}

rating ist eine Ganzzahl von 1 bis 5 oder null. Booking.com bewertet mit Punkten bis 10, also teilen wir durch zwei, runden und begrenzen auf 1–5. Steam hat keine Sterne, nur „empfohlen" oder „nicht empfohlen", was wir auf 5 und 1 abbilden. Manche Quellen erlauben eine Bewertung ganz ohne Wertung, dann ist das Feld null. Eine 0 schreiben wir nie: Sie sieht wie eine echte Wertung aus und drückt Durchschnittswerte nach unten.

text und title können null sein. Bewertungen mit nur einer Wertung sind in App-Stores üblich, und nur manche Plattformen haben Titel. Einen erfinden wir nicht aus dem ersten Satz.

url hat auf rein lesenden Plattformen eine bestimmte Bedeutung. Wenn wir keine Antwort veröffentlichen können, ist url der Ort, an dem das Unternehmen von Hand antworten kann. Versucht ein Client trotzdem zu antworten, trägt der Fehler dieselbe URL.

source existiert wegen der Aggregatoren. Viator liefert Bewertungen, die auf Viator und auf Tripadvisor geschrieben wurden. Ein Property Manager liefert Airbnb-, Booking.com- und Vrbo-Bewertungen über eine einzige Verbindung. platform sagt, über welche Verbindung die Bewertung gekommen ist; source sagt, auf welcher Website sie geschrieben wurde.

created_at und updated_at sind getrennt, weil Menschen Bewertungen bearbeiten. Eine bearbeitete Ein-Stern-Bewertung, die zu einer Vier-Stern-Bewertung wird, sollte ein Update sein, keine neue Zeile.

reply ist ein Objekt mit einem Status, kein String. Der Status ist published, queued, failed oder unknown. Der letzte muss erklärt werden. Manchmal geht die Anfrage an die Plattform raus, aber es kommt keine Antwort zurück, und die Plattform bietet keine Möglichkeit, die Antwort zurückzulesen. Ein erneuter Versuch könnte dieselbe Antwort doppelt veröffentlichen – im Namen des Unternehmens. Also brechen wir ab, markieren sie als unknown und weisen den Client an, vor dem erneuten Absenden die Plattform zu prüfen. Ein Status, der sagt „wir wissen es nicht", ist nützlicher als eine Vermutung.

Diagram of reply statuses: a reply is accepted with 202 and queued, then ends as published, failed or unknown

Längenbegrenzungen für Antworten werden pro Plattform geprüft, bevor eine Antwort in die Warteschlange kommt: 4.096 Bytes bei Google Business Profile, 350 Zeichen bei Google Play, 80 bei eBay. Ein Emoji ist ein Zeichen, aber vier Bytes, daher zählen wir Code Points für Zeichenlimits und Bytes für Bytelimits.

Stabile IDs und Deduplizierung

Dubletten sind der Fehler, den Clients zuerst bemerken. Unsere Regel ist einfach: Jeder Connector muss für jede Bewertung die eigene ID der Plattform zurückgeben, und die Datenbank hat einen Unique-Index auf (location_id, external_id). Ein zweiter Sync derselben Bewertung ist ein Update, nie ein Insert. Standorte funktionieren genauso, mit einem Unique-Index auf (connection_id, external_id).

Das Schwierige daran ist, dass „die eigene ID der Plattform" nicht immer existiert:

Clients sehen Plattform-IDs nie als Primärschlüssel. Sie bekommen unsere eigenen IDs mit einem Typ-Präfix und einem zeitlich geordneten Körper (rev_01KJ…, loc_01KJ…, req_01KJ…). Das Präfix macht eine falsch platzierte ID in Logfiles sofort erkennbar, und die Ordnung hilft bei der Paginierung: Der Cursor kodiert Zeitstempel und ID des letzten Elements, sodass eine Seitengrenze stabil bleibt, während neue Bewertungen eintreffen.

Wiederverbindung. Ein Unternehmen trennt ein Konto und verbindet es eine Woche später erneut. Neue Standorte anzulegen würde jede Bewertung duplizieren. Stattdessen wird ein Standort, der vor weniger als 30 Tagen getrennt wurde und dieselbe externe ID hat, reaktiviert: dieselben IDs, keine doppelten Bewertungen.

Löschungen. Eine von der Plattform entfernte Bewertung erscheint einfach nicht mehr. Nichts weist dich darauf hin. Bei 60 der 84 Quellen können wir die vollständige Historie lesen, daher lesen wir sie periodisch erneut (alle 25 Tage bei Google Business Profile, dessen Bedingungen nicht erlauben, Inhalte länger als 30 Tage unbestätigt zu halten; wöchentlich bei den meisten anderen) und markieren Bewertungen, die die Plattform nicht mehr zurückgibt, mit deleted_at, plus einen review.deleted-Webhook. Die entscheidende Absicherung: Wenn ein Lesevorgang vorzeitig abbrach, wegen eines Timeouts oder eines Seitenlimits, markieren wir nichts. „Ich habe es nicht gesehen" als „es ist weg" zu behandeln, würde echte Bewertungen löschen. Google Play ist wegen seines Sieben-Tage-Fensters ausgeschlossen.

Vertragstests gegen die OpenAPI-Spezifikation

Der Vertrag ist ein OpenAPI-3.1-Dokument mit 18 Pfaden, 30 Schemas und 9 Webhook-Events. Zwei Arten von Tests halten es ehrlich.

Der erste ist billig und läuft bei jedem Commit: Die Enums der Spec müssen exakt mit dem Code übereinstimmen. Die Plattform-IDs in der Spec müssen der Liste in der Plattform-Konfiguration entsprechen, und die Webhook-Events in der Spec müssen den Event-Typen entsprechen, die der Code ausgeben kann. Generierte Clients verwerfen ihnen unbekannte Enum-Werte, also würde eine Plattform, die im Code, aber nicht in der Spec auftaucht, diese Clients beim ersten Sync brechen.

Der zweite ist ein Testmodus. API-Schlüssel gibt es in zwei Varianten, pk_live_… und pk_test_…, gegen denselben Server. Ein Test-Schlüssel leitet jede Plattform an einen Test-Connector: deterministische Beispiel-Standorte und -Bewertungen im Stil der echten (ein Café auf Google, eine App im App Store, ein Hotel auf Booking.com), Antworten, die akzeptiert und nirgendwo veröffentlicht werden, und auf rein lesenden Plattformen ein url auf jeder Bewertung, weil die Doku eines verspricht. Jeder kann den gesamten Vertrag durchlaufen, Schreibpfade inklusive, ohne ein echtes Konto zu berühren.

Die folgenden Beispiele sind die aus der Spec, mit URLs ersetzt durch example.com. Eine Listenanfrage:

GET /v1/reviews?platform=google&limit=1
Authorization: Bearer pk_test_…

liefert die weiter oben gezeigte Bewertung innerhalb von data, plus einen next_cursor. Eine Antwort an eine Plattform, die Antworten unterstützt, wird mit 202 akzeptiert, und die Bewertung kommt mit ihrer Antwort in der Warteschlange zurück (andere Felder weggelassen):

POST /v1/reviews/rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E/reply
Authorization: Bearer pk_test_…
Content-Type: application/json

{ "text": "Thanks Marta! We have added a second barista at lunch." }
{
  "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E",
  "platform": "google",
  "reply": {
    "text": "Thanks Marta! We have added a second barista at lunch.",
    "created_at": null,
    "status": "queued",
    "error": null
  }
}

Die interessanten Fälle sind die Fehler. Jeder Fehler hat dieselbe Form (type, code, message, retryable, request_id, docs_url), und manche Codes ergänzen Felder, auf die ein Client reagieren kann. Eine Antwort auf eine Yelp-Bewertung liefert 422:

{
  "error": {
    "type": "invalid_request_error",
    "code": "reply_not_supported",
    "message": "Yelp has no reply API for third parties, so Prisma only reads its reviews. Answer this one on the platform: https://example.com/biz/example-cafe-madrid",
    "retryable": false,
    "request_id": "req_01KJ8T3C5D7E9F1G3H5J7K9M1N",
    "docs_url": "https://example.com/docs/errors#reply_not_supported",
    "platform": "yelp",
    "url": "https://example.com/biz/example-cafe-madrid"
  }
}

Eine Antwort über das Limit der Plattform hinaus liefert ebenfalls 422, mit code: "reply_too_long", platform: "google_play" und max_length: 350. Clients sollten auf code verzweigen, nie auf message: Die Message ist für Menschen und kann sich ändern.

Dieselbe Form gilt im Live-Traffic. Dies ist eine echte Antwort aus der Produktion auf eine Anfrage ohne Schlüssel (Header gekürzt, Docs-URL ersetzt):

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: req_01K6VVGDM8CFFJEQ3MNWWR582S

{"error":{"type":"authentication_error","code":"missing_api_key","message":"Send your API key as \"Authorization: Bearer pk_live_…\".","retryable":false,"request_id":"req_01K6VVGDM8CFFJEQ3MNWWR582S","docs_url":"https://example.com/docs/errors#missing_api_key"}}

Die request_id im Body stimmt mit dem Request-Id-Header überein. Für jede Operation prüfen wir den Statuscode, dass der Body gegen sein Schema validiert (alle 14 Bewertungsfelder vorhanden, Nullable-Typen wo deklariert), die Fehlerform bei jeder Nicht-2xx-Antwort sowie die Request-Id- und Rate-Limit-Header bei Erfolg.

Dieselben Prüfungen mit Apidog CLI ausführen

Dieselben Prüfungen funktionieren bei jeder API, die eine OpenAPI-Datei mitliefert. Die Apidog CLI importiert die Spec, und ein Coding-Agent wie Claude Code schreibt und führt die Testfälle aus. Einmalig einrichten:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install
Terminal showing Apidog CLI setup and the apidog import command loading an OpenAPI file into a project

Dann gib dem Agenten einen Prompt:

Import ./openapi.json into Apidog project <projectId>. Create test cases for the
list reviews and reply endpoints that assert the status code, that the body
validates against its schema with all 14 review fields present, and that the
Request-Id header is set. Add a case that replies to a Yelp review and expects
422 with code reply_not_supported. Run them against the test environment and
summarize any failures.

Der Agent importiert die Spec, liest das Testfall-Schema, validiert seine Payload, erstellt den Testfall und führt ihn aus:

apidog import --project <projectId> --format openapi --file ./openapi.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,junit
Terminal showing Apidog CLI validating a test case file, creating the test case and running it with CLI and JUnit reporters

Der junit-Reporter schreibt eine Datei, die deine CI lesen kann, sodass derselbe Lauf jeden Pull Request absichern kann. Der Apidog-CLI-CI/CD-Leitfaden behandelt die Pipeline-Einrichtung.

Erkenntnisse

„Hat eine API" und „kann antworten" als getrennte Eigenschaften modellieren. Atlassian und Microsoft zeigen, dass eine API existieren kann und trotzdem keine Antworten annimmt. Ein Flag für beides würde Antworten versprechen, die wir nicht liefern können.

Den unknown-Antwortstatus einplanen, bevor die erste Antwort rausgeht. Ein Zustand, der Unsicherheit zugibt, kostet einen Enum-Wert; eine doppelte öffentliche Antwort kostet das Vertrauen eines Kunden.

Nicht darauf vertrauen, dass eine Plattform-ID existiert oder stabil bleibt. Pro Connector festhalten, woher die ID stammt und was sie ändern würde.

Die Spec gegen den Code testen, nicht nur den Code gegen die Spec. Der Enum-Test ist etwa zehn Zeilen lang, und er bewahrt vor genau dem Fehler, der generierte Clients am härtesten trifft.

Praktizieren Sie API Design-First in Apidog

Entdecken Sie eine einfachere Möglichkeit, APIs zu erstellen und zu nutzen