私はPrisma Reviewsという、84のプラットフォームから顧客レビューを取得し、単一のJSON形式で返す小さなAPIを運営しています。この記事は製品についてではありません。私たちの時間の大半を費やした3つのエンジニアリング上の課題についてです。それは、非常に異なる形式を持つソースに対応するスキーマの設計、同じレビューが二度表示されないようIDを安定させること、そして上流の変更が下流のクライアントを静かに壊さないようコントラクトをテストすることです。
まず最初に一つ。これは他のすべてに影響する重要な点ですが、すべてのレビューソースがAPIを持っているわけではありません。84のソースのうち、公式APIを持つのは59です。残りの25は持っておらず、代わりに公開ページやフィードを読み取っています。
すべてのソースがAPIというわけではない
設定内のすべてのプラットフォームには3つの属性があります。ビジネスがどう接続するか、返信を投稿できるか、新しいレビューがどう届くかです。84のソースを読み取り方法で分類すると、4つのグループになります。
| グループ | ソース数 | 例 |
|---|---|---|
| 公式API(ビジネス自身の認証情報またはOAuth) | 50 | Google Business Profile(承認待ち)、App Store、Google Play、Trustpilot(承認待ち)、Judge.me、Yotpo、eBay、Wix、WooCommerce、Shopware、HostawayやGuestyなどのプロパティマネージャー |
| 公式公開API(ビジネス認証情報不要) | 9 | Steam、Etsy、Salesforce AppExchange、Atlassian Marketplace、VS Code Marketplace、Open VSX、JetBrains Marketplace、Thunderbird Add-ons、Viator |
| APIなし:公開ページまたはフィード | 3 | Shopify App Store(HTMLレビューページ)、WordPress.org(RSSレビューフィード)、Apple Podcasts(公開レビューフィード) |
| APIなし:有料データプロバイダー | 22 | Google Maps、Yelp、Tripadvisor、Booking.com、Facebook、Airbnb、Expedia、Capterra、OpenTable |

これらのグループの違いは、API設計にも影響しています。
- 認証。最初のグループはOAuthフローか、ビジネスが貼り付けるキーが必要です。他の3つのグループは、リスティングの公開URLだけで済みます。
- 返信。84のソースのうち、サードパーティが返信を投稿できるのは25のみで、そのうちGoogle Business ProfileとTrustpilotの2つは、プラットフォームによるアクセス承認をまだ待っています。APIがあるだけでは十分ではありません。Atlassianの返信エンドポイントは現在
410 API_DEPRECATEDを返し、Microsoft Storeの返信APIはMicrosoft側で壊れているため、両方とも読み取り専用です。 - コストと頻度。公式APIは呼び出しごとのコストがかからないため、頻繁にチェックします。データプロバイダー経由の読み取りはレビューごとに課金され、プロバイダーによっては新着分の実行ごとに課金するものもあるため、それらのソースは1日1回チェックします。
- APIが存在しない理由。Expediaの返信付きパートナーAPIはフルチャネルマネージャーにのみ開放されており、私たちは拒否されました。AirbnbのAPIは招待制です。ShopifyにはレビューAPIがなく、アプリ開発者は自社のダッシュボードで返信します。
同じプラットフォームが2回登場するケースもあります。AirbnbとBooking.comのレビューは、公開ページから(読み取り専用で)取得できるほか、返信を許可するプロパティマネージャーの公式API経由でも取得できます。これが後述するフィールドの一つの理由です。
すべてに共通する単一のスキーマ
すべてのレビューは、どのソースからであっても同じ14個のフィールドを持ち、それらはすべて常に存在します。プラットフォームがデータを提供しない場合、そのフィールドは欠落するのではなく null になります。欠落したキーと null は人間には同じ意味ですが、型付けされたクライアントには異なり、「常に存在する」はテストが容易です。
{
"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 は1から5の整数、または null です。Booking.comは10点満点なので、2で割り、四捨五入して1〜5に丸めます(クランプ)。Steamには星がなく、「おすすめ」か「おすすめしない」だけなので、それぞれ5と1にマッピングします。評価のないレビューを許容するソースもあり、その場合はフィールドが null になります。0を書き込むことは決してありません。0は実際のスコアのように見え、平均を下げてしまうからです。
text と title は null になり得ます。評価のみのレビューはアプリストアでよく見られ、タイトルがあるのは一部のプラットフォームだけです。最初の文からタイトルを作り出すことはしません。
url は読み取り専用プラットフォームでは特別な意味を持ちます。返信を投稿できない場合、url はビジネスが手動で返信できる場所を示します。クライアントがそれでも返信しようとした場合、エラーには同じURLが含まれます。
source はアグリゲーターがあるために存在します。ViatorはViator上とTripadvisor上で書かれたレビューを返します。プロパティマネージャーは1つの接続でAirbnb、Booking.com、Vrboのレビューを返します。platform はレビューがどの接続を経由してきたかを示し、source はどのサイト上で書かれたかを示します。
created_at と updated_at は別のフィールドです。人はレビューを編集するからです。1つ星から4つ星に編集されたレビューは、新しい行ではなく更新として扱われるべきです。
reply は文字列ではなく、ステータスを持つオブジェクトです。ステータスは published、queued、failed、unknown のいずれかです。最後のものには説明が必要です。プラットフォームへのリクエストが送信されたものの応答が返ってこず、プラットフォームから返信を読み戻す方法がないことがあります。リトライすると、ビジネスの名義で同じ返信が二重に投稿される可能性があります。そこで私たちは処理を止め、unknown とマークし、再投稿する前にプラットフォームを確認するようクライアントに伝えます。「わからない」と示すステータスは、当てずっぽうより有用です。

返信の長さ制限は、キューに入れる前にプラットフォームごとにチェックされます。Google Business Profileは4,096バイト、Google Playは350文字、eBayは80文字です。絵文字は1文字だが4バイトなので、文字数制限にはコードポイントを、バイト数制限にはバイトを数えます。
安定したIDと重複排除
重複は、クライアントが最初に気づくバグです。ルールはシンプルです。各コネクタはすべてのレビューについてプラットフォーム独自のIDを返すこと、そしてデータベースには (location_id, external_id) に一意インデックスを張ること。同じレビューの2回目の同期は挿入ではなく更新になります。ロケーションも同様に、(connection_id, external_id) に一意インデックスを持ちます。
難しいのは、「プラットフォーム独自のID」が常に存在するとは限らないことです。
- Etsyのレビューには独自のIDがありません。各レビューは正確に1つのトランザクションに属するため、トランザクションIDをレビューIDとして使います。
- WordPress.org はフィードにレビューIDを提供しません。各レビューはフォーラムトピックなので、トピックのスラッグを使用します。
- Shopify App Storeのページは、HTMLにレビューのコンテンツIDを持っています。私たちはそれに依存していますが、ページの再デザインで変更される可能性があることも承知しています。
- Google Play には実際のIDがありますが、そのAPIは過去7日間に作成または編集されたレビューしか返しません。保存された履歴は私たちのものであり、再読み取りはできません。
クライアントがプラットフォームのIDを主キーとして目にすることは決してありません。クライアントが受け取るのは、タイププレフィックスと時系列順の本体を持つ独自のIDです(rev_01KJ…、loc_01KJ…、req_01KJ…)。プレフィックスにより、ログで間違ったIDがすぐ目立ちます。また、順序付けはページネーションに役立ちます。カーソルは最後の項目のタイムスタンプとIDをエンコードするため、新しいレビューが届いてもページの境界は動きません。
再接続。ビジネスがアカウントを切断し、1週間後に再接続するケースがあります。新しいロケーションを作ると、すべてのレビューが重複してしまいます。代わりに、同じ外部IDを持ち、切断から30日未満のロケーションは再有効化されます。同じIDのまま、レビューの重複はありません。
削除。プラットフォームから削除されたレビューは、単に表示されなくなります。何も通知はありません。84のソースのうち60では全履歴を読み取れるため、定期的に再読み取りし(Google Business Profileは25日ごと——その利用規約ではコンテンツを30日以上未確認のまま保持できないため、他の多くは週ごと)、プラットフォームが返さなくなったレビューに deleted_at をマークし、review.deleted Webhookを送ります。重要な保護策として、タイムアウトやページ上限などで読み取りが途中で止まった場合は、何もマークしません。「見なかった」を「消えた」と扱うと、実際のレビューが削除されてしまいます。Google Playは7日間のウィンドウがあるため対象外です。
OpenAPI仕様に対するコントラクトテスト
コントラクトは、18パス、30スキーマ、9つのWebhookイベントを持つOpenAPI 3.1ドキュメントです。それを正しく保つために、2種類のテストを行っています。
1つ目は安価で、すべてのコミットで実行されます。仕様のenumがコードと正確に一致することを確認するものです。仕様内のプラットフォームIDはプラットフォーム設定のリストと一致しなければならず、仕様内のWebhookイベントはコードが発行できるイベントタイプと一致しなければなりません。生成されたクライアントは知らないenum値を拒否するため、コードには追加されたが仕様にはないプラットフォームは、それらのクライアントの初回同期を壊してしまいます。
2つ目はテストモードです。APIキーには pk_live_… と pk_test_… の2種類があり、同じサーバーに対して使われます。テストキーはすべてのプラットフォームをテスト用コネクタにルーティングします。実物に似た決定論的なサンプルロケーションとレビュー(Googleのカフェ、App Storeのアプリ、Booking.comのホテル)、どこにも公開されないが受け付けられる返信、そして読み取り専用プラットフォームではすべてのレビューに url が付きます。ドキュメントがその存在を約束しているからです。誰でも書き込みパスを含むコントラクト全体を、実際のアカウントに触れずに実行できます。
以下の例は仕様に含まれるもので、URLはexample.comに置き換えています。リスト取得リクエスト:
GET /v1/reviews?platform=google&limit=1
Authorization: Bearer pk_test_…は、先ほど示したレビューを data の中に、next_cursor とともに返します。返信をサポートするプラットフォームへの返信は 202 で受け付けられ、レビューはキューに入った返信とともに返ってきます(他のフィールドは省略):
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
}
}興味深いのは失敗のケースです。すべてのエラーは同じ形状を持ち(type、code、message、retryable、request_id、docs_url)、一部のコードはクライアントが対応できるフィールドを追加します。Yelpのレビューへの返信は 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"
}
}プラットフォームの制限を超える返信も 422 を返し、code: "reply_too_long"、platform: "google_play"、max_length: 350 が付きます。クライアントは code で分岐すべきで、message で分岐してはいけません。メッセージは人間向けであり、変更される可能性があります。
同じ形状は本番トラフィックでも保たれます。これは、キーなしのリクエストに対する本番環境からの実際のレスポンスです(ヘッダーは省略、ドキュメントURLは置き換え済み):
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"}}ボディの request_id は Request-Id ヘッダーと一致します。各操作について、ステータスコード、ボディがスキーマに対して検証されること(14個すべてのレビューフィールドが存在し、宣言された箇所ではnull許容型であること)、すべての非2xxレスポンスでのエラー形状、そして成功時の Request-Id とレート制限ヘッダーをチェックします。
Apidog CLIで同じチェックを実行する
同じチェックは、OpenAPIファイルを提供するあらゆるAPIで機能します。Apidog CLI が仕様をインポートし、Claude Codeのようなコーディングエージェントがテストケースを作成・実行します。一度だけセットアップすればよいのです:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install
次に、エージェントに1つのプロンプトを与えます:
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.エージェントは仕様をインポートし、テストケースのスキーマを読み、ペイロードを検証し、ケースを作成して実行します:
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
junit レポーターはCIが読めるファイルを書き出すため、同じ実行をすべてのプルリクエストのゲートにできます。パイプラインのセットアップについては、Apidog CLI CI/CDガイドを参照してください。
学んだこと
「APIを持つ」と「返信できる」は別の属性としてモデル化する。AtlassianとMicrosoftが示すように、APIが存在しても返信を受け付けないことがあります。両方を1つのフラグにすると、提供できない返信を約束してしまいます。
最初の返信を送る前に、unknown 返信状態への備えをする。不確実性を認める状態はenum値1つで済みますが、公開返信の重複は顧客の信頼を失わせます。
プラットフォームIDが存在し、安定していると信じない。コネクタごとに、IDがどこから来るのか、何がそれを変えうるのかを書き留めておきましょう。
仕様をコードに対してテストする。コードを仕様に対してテストするだけでは不十分。enumテストは10行ほどですが、生成クライアントに最も痛いダメージを与える障害を防いでくれます。
