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:
| Gruppe | Quellen | Beispiele |
|---|---|---|
| Offizielle API, eigene Zugangsdaten des Unternehmens oder OAuth | 50 | Google 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 Unternehmens | 9 | Steam, Etsy, Salesforce AppExchange, Atlassian Marketplace, VS Code Marketplace, Open VSX, JetBrains Marketplace, Thunderbird Add-ons, Viator |
| Keine API: öffentliche Seite oder Feed | 3 | Shopify App Store (HTML-Bewertungsseite), WordPress.org (RSS-Bewertungsfeed), Apple Podcasts (öffentlicher Bewertungsfeed) |
| Keine API: kostenpflichtiger Datenanbieter | 22 | Google Maps, Yelp, Tripadvisor, Booking.com, Facebook, Airbnb, Expedia, Capterra, OpenTable |

Die Gruppen unterscheiden sich in punkten, die sich bis in das API-Design hineinziehen:
- Authentifizierung. Die erste Gruppe benötigt einen OAuth-Flow oder einen Schlüssel, den das Unternehmen einfügt. Die anderen drei brauchen nur die öffentliche URL eines Eintrags.
- Antworten. Nur 25 der 84 Quellen erlauben einem Drittanbieter, eine Antwort zu veröffentlichen, und bei zwei davon, Google Business Profile und Trustpilot, warten wir noch auf die Freigabe der Plattform. Eine API zu haben, reicht nicht aus: Atlassians Antwort-Endpoint antwortet mittlerweile mit
410 API_DEPRECATED, und die Antwort-API des Microsoft Store ist auf Microsofts Seite defekt, sodass beide nur lesend sind. - Kosten und Takt. Offizielle APIs kosten uns nichts pro Aufruf, daher prüfen wir sie häufig. Das Auslesen über einen Datenanbieter wird pro Bewertung abgerechnet, und einige Anbieter verlangen pro Lauf pauschal, was auch immer neu ist – diese Quellen werden daher einmal täglich geprüft.
- Warum es keine API gibt. Expedis Partner-API mit Antworten ist nur für vollwertige Channel Manager offen, und sie hat uns abgelehnt. Die von Airbnb ist nur auf Einladung zugänglich. Shopify hat keine Bewertungs-API; App-Entwickler antworten in ihrem eigenen Dashboard.
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.

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:
- Etsy-Bewertungen haben keine eigene ID. Jede Bewertung gehört zu genau einer Transaktion, daher ist die Transaktions-ID die Bewertungs-ID.
- WordPress.org liefert im Feed keine Bewertungs-ID. Jede Bewertung ist ein Forenthema, daher verwenden wir den Topic-Slug.
- Die Shopify-App-Store-Seite trägt eine Content-ID der Bewertung in ihrem HTML. Wir verlassen uns darauf, wohl wissend, dass ein Redesign der Seite sie ändern könnte.
- Google Play hat echte IDs, aber die API liefert nur Bewertungen, die in den letzten sieben Tagen erstellt oder bearbeitet wurden. Die gespeicherte Historie gehört uns, und wir können sie nicht erneut auslesen.
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
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
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.
