Tiga Masalah Rekayasa di Balik API Agregasi Ulasan dari 84 Platform
Saya menjalankan Prisma Reviews, sebuah API kecil yang mengembalikan ulasan pelanggan dari 84 platform dalam satu format JSON. Tulisan ini bukan tentang produknya. Ini tentang tiga masalah rekayasa yang menghabiskan sebagian besar waktu kami: merancang skema yang cocok untuk sumber dengan bentuk yang sangat berbeda, menjaga ID tetap stabil agar ulasan yang sama tidak pernah muncul dua kali, dan menguji kontrak agar perubahan di hulu tidak diam-diam merusak klien di hilir.
Satu hal dulu, karena hal ini membentuk segalanya: tidak semua sumber ulasan adalah API. Dari 84 sumber kami, 59 memiliki API resmi. 25 lainnya tidak, dan kami membaca halaman publik atau feed mereka sebagai gantinya.
Tidak semua sumber adalah API
Setiap platform dalam konfigurasi kami memiliki tiga properti: cara bisnis menghubungkannya, apakah kami bisa mempublikasikan balasan, dan bagaimana ulasan baru sampai ke kami. Mengelompokkan 84 sumber berdasarkan cara kami membacanya menghasilkan empat kelompok:
| Kelompok | Sumber | Contoh |
|---|---|---|
| API resmi, kredensial milik bisnis sendiri atau OAuth | 50 | Google Business Profile (akses masih menunggu), App Store, Google Play, Trustpilot (akses masih menunggu), Judge.me, Yotpo, eBay, Wix, WooCommerce, Shopware, pengelola properti seperti Hostaway dan Guesty |
| API publik resmi, tanpa kredensial bisnis | 9 | Steam, Etsy, Salesforce AppExchange, Atlassian Marketplace, VS Code Marketplace, Open VSX, JetBrains Marketplace, Thunderbird Add-ons, Viator |
| Tanpa API: halaman atau feed publik | 3 | Shopify App Store (halaman HTML ulasan), WordPress.org (feed RSS ulasan), Apple Podcasts (feed ulasan publik) |
| Tanpa API: penyedia data berbayar | 22 | Google Maps, Yelp, Tripadvisor, Booking.com, Facebook, Airbnb, Expedia, Capterra, OpenTable |
Kelompok-kelompok ini berbeda dengan cara yang memengaruhi desain API:
- Autentikasi. Kelompok pertama memerlukan alur OAuth atau kunci yang ditempel bisnis. Tiga kelompok lainnya hanya memerlukan URL publik dari sebuah listing.
-
Balasan. Hanya 25 dari 84 sumber yang memungkinkan pihak ketiga mempublikasikan balasan, dan dua di antaranya, Google Business Profile dan Trustpilot, masih menunggu persetujuan akses dari platform tersebut. Memiliki API saja tidak cukup: endpoint balasan Atlassian kini menjawab
410 API_DEPRECATED, dan API balasan Microsoft Store rusak di sisi Microsoft, sehingga keduanya hanya bisa dibaca. - Biaya dan frekuensi. API resmi tidak membebani biaya per panggilan, jadi kami memeriksanya sering. Membaca melalui penyedia data ditagih per ulasan, dan beberapa penyedia mengenakan biaya per run apa pun yang baru, sehingga sumber-sumber tersebut diperiksa sekali sehari.
- Mengapa tidak ada API. API mitra Expedia dengan balasan hanya terbuka untuk channel manager penuh, dan mereka menolak kami. API Airbnb hanya dengan undangan. Shopify tidak memiliki API ulasan; pengembang aplikasi menjawab di dashboard mereka sendiri.
Beberapa platform muncul dua kali. Ulasan Airbnb dan Booking.com bisa datang dari halaman publik (hanya baca), atau melalui API resmi pengelola properti, yang memang mengizinkan balasan. Itulah alasan adanya salah satu field di bawah ini.
Satu skema untuk semuanya
Setiap ulasan, dari setiap sumber, memiliki 14 field yang sama, dan semuanya selalu ada. Ketika sebuah platform tidak memberikan sesuatu, field tersebut bernilai null, tidak pernah hilang. Kunci yang hilang dan null bermakna sama bagi manusia, tetapi tidak bagi klien yang bertipe, dan "selalu ada" mudah untuk diuji.
{
"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 adalah bilangan bulat dari 1 sampai 5, atau null. Booking.com menggunakan skala 10, jadi kami bagi dua, bulatkan, dan batasi ke 1-5. Steam tidak punya bintang, hanya "direkomendasikan" atau "tidak direkomendasikan", yang kami petakan ke 5 dan 1. Beberapa sumber mengizinkan ulasan tanpa rating sama sekali, dan field-nya menjadi null. Kami tidak pernah menulis 0: itu terlihat seperti skor nyata dan menurunkan rata-rata.
text dan title bisa null. Ulasan hanya rating umum di toko aplikasi, dan hanya beberapa platform yang memiliki judul. Kami tidak membuat judul dari kalimat pertama.
url punya makna khusus pada platform yang hanya bisa dibaca. Ketika kami tidak bisa mempublikasikan balasan, url adalah tempat bisnis dapat menjawabnya secara manual. Jika klien tetap mencoba membalas, pesan error membawa URL yang sama.
source ada karena aggregator. Viator mengembalikan ulasan yang ditulis di Viator dan di Tripadvisor. Pengelola properti mengembalikan ulasan Airbnb, Booking.com, dan Vrbo melalui satu koneksi. platform menunjukkan koneksi mana yang dilalui ulasan; source menunjukkan situs mana ulasan itu ditulis.
created_at dan updated_at dipisahkan karena orang mengedit ulasan. Ulasan satu bintang yang diedit menjadi empat bintang seharusnya menjadi update, bukan baris baru.
reply adalah objek dengan status, bukan string. Statusnya adalah published, queued, failed, atau unknown. Yang terakhir perlu dijelaskan. Kadang-kadang permintaan ke platform terkirim tetapi tidak ada jawaban yang kembali, dan platform tidak punya cara untuk membaca balasan tersebut kembali. Mencoba lagi bisa mempublikasikan balasan yang sama dua kali, atas nama bisnis. Jadi kami berhenti, menandainya unknown, dan meminta klien memeriksa platform sebelum mengirim lagi. Status yang mengatakan "kami tidak tahu" lebih berguna daripada menebak.
Batas panjang balasan diperiksa per platform sebelum balasan masuk antrean: 4.096 byte di Google Business Profile, 350 karakter di Google Play, 80 di eBay. Emoji adalah satu karakter tetapi empat byte, jadi kami menghitung code point untuk batas karakter dan byte untuk batas byte.
ID stabil dan deduplikasi
Duplikat adalah bug yang paling pertama diperhatikan klien. Aturan kami sederhana: setiap connector harus mengembalikan ID milik platform untuk setiap ulasan, dan basis data memiliki indeks unik pada (location_id, external_id). Sinkronisasi kedua dari ulasan yang sama adalah update, bukan insert. Lokasi bekerja dengan cara yang sama, dengan indeks unik pada (connection_id, external_id).
Bagian sulitnya adalah "ID milik platform" tidak selalu ada:
- Ulasan Etsy tidak punya ID sendiri. Setiap ulasan berhubungan dengan tepat satu transaksi, jadi ID transaksi menjadi ID ulasan.
- WordPress.org tidak memberikan ID ulasan dalam feed-nya. Setiap ulasan adalah topik forum, jadi kami menggunakan slug topik.
- Halaman Shopify App Store membawa ID konten ulasan di HTML-nya. Kami mengandalkannya, sambil tahu bahwa desain ulang halaman bisa mengubahnya.
- Google Play memiliki ID nyata, tetapi API-nya hanya mengembalikan ulasan yang dibuat atau diedit dalam tujuh hari terakhir. Riwayat yang tersimpan adalah milik kami, dan kami tidak bisa membacanya kembali.
Klien tidak pernah melihat ID platform sebagai primary key. Mereka mendapat ID kami sendiri dengan prefiks tipe dan bagian isi yang terurut berdasarkan waktu (rev_01KJ…, loc_01KJ…, req_01KJ…). Prefiks membuat ID yang salah tempat terlihat jelas di log, dan pengurutannya membantu paginasi: cursor mengodekan timestamp dan ID dari item terakhir, sehingga batas halaman tetap stabil saat ulasan baru datang.
Penyambungan ulang. Sebuah bisnis memutus koneksi akun dan menyambungkannya kembali seminggu kemudian. Membuat lokasi baru akan menduplikasi setiap ulasan. Sebagai gantinya, lokasi yang terputus kurang dari 30 hari dengan external ID yang sama diaktifkan kembali: ID yang sama, tanpa ulasan duplikat.
Penghapusan. Ulasan yang dihapus dari platform begitu saja berhenti muncul. Tidak ada yang memberi tahu Anda. Untuk 60 dari 84 sumber kami bisa membaca seluruh riwayat, jadi kami membacanya kembali secara berkala (setiap 25 hari untuk Google Business Profile, yang ketentuannya tidak mengizinkan kami menyimpan konten tanpa konfirmasi lebih dari 30 hari; mingguan untuk kebanyakan lainnya) dan menandai ulasan yang tidak lagi dikembalikan platform dengan deleted_at, ditambah webhook review.deleted. Pengaman utamanya: jika sebuah pembacaan berhenti lebih awal, karena timeout atau batas halaman, kami tidak menandai apa pun. Memperlakukan "saya tidak melihatnya" sebagai "sudah hilang" akan menghapus ulasan nyata. Google Play dikecualikan karena jendela tujuh harinya.
Pengujian kontrak terhadap spesifikasi OpenAPI
Kontrak kami adalah dokumen OpenAPI 3.1 dengan 18 path, 30 schema, dan 9 event webhook. Dua jenis pengujian menjaganya tetap akurat.
Yang pertama murah dan berjalan di setiap commit: enum pada spesifikasi harus cocok persis dengan kode. ID platform dalam spesifikasi harus sama dengan daftar di konfigurasi platform, dan event webhook dalam spesifikasi harus sama dengan tipe event yang bisa dipancarkan kode. Klien yang dihasilkan menolak nilai enum yang tidak mereka kenal, jadi platform yang ditambahkan ke kode tetapi tidak ke spesifikasi akan merusak klien-klien tersebut pada sinkronisasi pertama mereka.
Yang kedua adalah mode test. Kunci API datang dalam dua jenis, pk_live_… dan pk_test_…, ke server yang sama. Kunci test mengarahkan setiap platform ke connector test: lokasi dan ulasan contoh yang deterministik dan berbentuk seperti aslinya (kafe di Google, aplikasi di App Store, hotel di Booking.com), balasan yang diterima tetapi tidak pernah dipublikasikan ke mana pun, dan di platform hanya-baca sebuah url di setiap ulasan, karena dokumentasi menjanjikannya. Siapa pun bisa menjalankan seluruh kontrak, termasuk path tulis, tanpa menyentuh akun nyata.
Contoh di bawah adalah contoh yang ada di spesifikasi, dengan URL diganti menjadi example.com. Permintaan daftar:
GET /v1/reviews?platform=google&limit=1
Authorization: Bearer pk_test_…
mengembalikan ulasan yang ditampilkan sebelumnya di dalam data, plus next_cursor. Balasan ke platform yang mendukung balasan diterima dengan 202, dan ulasan kembali dengan balasannya di antrean (field lain dihilangkan):
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
}
}
Kasus yang menarik adalah kegagalannya. Setiap error memiliki bentuk yang sama (type, code, message, retryable, request_id, docs_url), dan beberapa kode menambahkan field yang bisa ditindaklanjuti klien. Membalas ulasan Yelp mengembalikan 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"
}
}
Balasan yang melebihi batas platform juga mengembalikan 422, dengan code: "reply_too_long", platform: "google_play", dan max_length: 350. Klien sebaiknya bercabang berdasarkan code, tidak pernah berdasarkan message: pesan itu untuk manusia dan bisa berubah.
Bentuk yang sama berlaku pada traffic live. Ini adalah respons nyata dari produksi untuk permintaan tanpa kunci (header dipangkas, URL docs diganti):
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 di body cocok dengan header Request-Id. Untuk setiap operasi kami memeriksa kode status, bahwa body valid terhadap schema-nya (semua 14 field ulasan ada, tipe nullable di tempat yang dideklarasikan), bentuk error pada setiap respons non-2xx, serta header Request-Id dan rate-limit pada kasus sukses.
Jalankan pemeriksaan yang sama dengan Apidog CLI
Pemeriksaan yang sama berfungsi pada API apa pun yang menyertakan file OpenAPI. Apidog CLI mengimpor spesifikasi, dan agen koding seperti Claude Code menulis serta menjalankan test case-nya. Atur sekali saja:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install
Kemudian beri agen satu 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.
Agen mengimpor spesifikasi, membaca schema test case, memvalidasi payload-nya, membuat test case, dan menjalankannya:
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
Reporter junit menulis file yang bisa dibaca CI Anda, sehingga run yang sama bisa menjadi gerbang untuk setiap pull request. Panduan CI/CD Apidog CLI membahas pengaturan pipeline-nya.
Pelajaran
Modelkan "punya API" dan "bisa membalas" sebagai properti terpisah. Atlassian dan Microsoft menunjukkan bahwa API bisa ada dan tetap tidak menerima balasan. Satu flag untuk keduanya akan menjanjikan balasan yang tidak bisa kami berikan.
Rencanakan status balasan unknown sebelum balasan pertama terkirim. Status yang mengakui ketidakpastian hanya membutuhkan satu nilai enum; balasan publik yang duplikat menghabiskan kepercayaan pelanggan.
Jangan percaya bahwa ID platform ada atau tetap stabil. Catat, untuk setiap connector, dari mana ID itu berasal dan apa yang bisa mengubahnya.
Uji spesifikasi terhadap kode, bukan hanya kode terhadap spesifikasi. Tes enum hanya sekitar sepuluh baris, dan itu menjaga kegagalan yang paling merusak klien yang dihasilkan.




Top comments (0)