Prisma Reviews'ı yönetiyorum: 84 platformdan gelen müşteri yorumlarını tek bir JSON formatında döndüren küçük bir API. Bu yazı üründen bahsetmiyor; zamanımızın çoğunu alan üç mühendislik probleminden bahsediyor: biçimleri birbirinden çok farklı kaynaklara uyacak bir şema tasarlamak, ID'leri kararlı tutup aynı yorumun iki kez görünmesini engellemek ve sözleşmeyi test ederek upstream'deki bir değişikliğin downstream'deki istemcileri sessizce bozmamasını sağlamak.
Önce her şeyi şekillendiren bir noktayı belirtelim: her yorum kaynağı bir API değildir. 84 kaynağımızdan 59'unun resmi bir API'si var. Diğer 25'inkinde yok ve onların yerini onların herkese açık sayfalarını ya da akışlarını okuyarak alıyoruz.
Her kaynak bir API değildir
Yapılandırmamızdaki her platformun üç özelliği vardır: bir işletme nasıl bağlanır, bir yanıt yayınlayabilir miyiz ve yeni yorumlar bize nasıl ulaşır. 84 kaynağı nasıl okuduğumuza göre sıraladığımızda dört grup ortaya çıkıyor:
| Grup | Kaynaklar | Örnekler |
|---|---|---|
| Resmi API, işletmenin kendi kimlik bilgileri veya OAuth | 50 | Google Business Profile (erişim onay bekliyor), App Store, Google Play, Trustpilot (erişim onay bekliyor), Judge.me, Yotpo, eBay, Wix, WooCommerce, Shopware, Hostaway ve Guesty gibi mülk yöneticileri |
| Resmi herkese açık API, işletme kimlik bilgisi gerekmez | 9 | Steam, Etsy, Salesforce AppExchange, Atlassian Marketplace, VS Code Marketplace, Open VSX, JetBrains Marketplace, Thunderbird Add-ons, Viator |
| API yok: herkese açık sayfa veya akış | 3 | Shopify App Store (HTML yorumlar sayfası), WordPress.org (RSS yorum akışı), Apple Podcasts (herkese açık yorum akışı) |
| API yok: ücretli veri sağlayıcısı | 22 | Google Maps, Yelp, Tripadvisor, Booking.com, Facebook, Airbnb, Expedia, Capterra, OpenTable |

Gruplar, API tasarımına da yansıyan yönlerden farklılaşıyor:
- Kimlik doğrulama. İlk grup bir OAuth akışı ya da işletmenin yapıştıracağı bir anahtar gerektiriyor. Diğer üçü yalnızca listelemenin herkese açık URL'sini istiyor.
- Yanıtlar. 84 kaynağın yalnızca 25'i üçüncü bir tarafın yanıt yayınlamasına izin veriyor ve bunlardan ikisi, Google Business Profile ve Trustpilot, hâlâ platformun erişim onayımızı bekliyor. Bir API'nin var olması yeterli değil: Atlassian'ın yanıt uç noktası artık
410 API_DEPRECATEDdöndürüyor ve Microsoft Store yanıt API'si Microsoft tarafında bozuk durumda, dolayısıyla ikisi de salt okunur. - Maliyet ve sıklık. Resmi API'ler çağrı başına bize hiçbir şeyi mal olmuyor, bu yüzden sık sık kontrol ediyoruz. Bir veri sağlayıcısı üzerinden okumak yorum başına faturalandırılıyor ve bazı sağlayıcılar her çalıştırmada yenilikten bağımsız olarak ücret alıyor; dolayısıyla bu kaynaklar günde bir kez kontrol ediliyor.
- Neden API yok. Expedia'nın yanıt destekli partner API'si yalnızca tam yetkili kanal yöneticilerine açık ve bizi reddetti. Airbnb'ninkiler yalnızca davetiyeyle. Shopify'ın yorum API'si yok; uygulama geliştiricileri kendi panellerinde yanıtlıyor.
Bazı platformlar iki kez karşımıza çıkıyor. Airbnb ve Booking.com yorumları herkese açık bir sayfadan (salt okunur) gelebilir ya da yanıtlara izin veren bir mülk yöneticisinin resmi API'si üzerinden gelebilir. Aşağıdaki alanlardan birinin sebebi de bu.
Hepsi için tek bir şema
Her kaynaktan gelen her yorum, her zaman mevcut olan aynı 14 alana sahip. Bir platform bize bir şey vermediğinde alan null olur, asla eksik kalmaz. Eksik bir anahtar ile null bir insan için aynı anlama gelir ama tipli bir istemci için gelmez; üstelik "her zaman mevcut" kolayca test edilebilir.
{
"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 ile 5 arasında bir tam sayı ya da null'dur. Booking.com 10 üzerinden puan veriyor, dolayısıyla ikiye bölüyor, yuvarlıyor ve 1–5 aralığına sabitliyoruz. Steam'in yıldızı yok; yalnızca "önerilen" ya da "önerilmez" var, bunları 5 ve 1'e eşliyoruz. Bazı kaynaklar hiç puan içermeyen bir yoruma izin veriyor; o zaman alan null oluyor. Hiç zaman 0 yazmıyoruz: gerçek bir puan gibi görünür ve ortalamaları aşağı çeker.
text ve title null olabilir. Yalnızca puan içeren yorumlar uygulama mağazalarında yaygındır ve yalnızca bazı platformlarda başlık vardır. İlk cümleden bir başlık uydurmuyoruz.
url, salt okunur platformlarda çok özel bir anlam taşır. Bir yanıt yayınlayamadığımızda, url işletmenin yorumu elle yanıtlayabileceği yerdir. Bir istemci yine de yanıt vermeyi denerse, hata aynı URL'yi taşır.
source alanı, toplayıcılar yüzünden vardır. Viator, hem Viator'da hem Tripadvisor'da yazılmış yorumları döndürür. Bir mülk yöneticisi tek bir bağlantı üzerinden Airbnb, Booking.com ve Vrbo yorumlarını döndürür. platform yorumun hangi bağlantıdan geldiğini söyler; source hangi sitede yazıldığını söyler.
created_at ile updated_at ayrıdır, çünkü insanlar yorumları düzenler. Düzenlenip bir yıldızdan dört yıldıza dönüşen bir yorum yeni bir satır değil, bir güncelleme olmalıdır.
reply, bir dizi değil, bir durumu olan bir nesnedir. Durum published, queued, failed ya da unknown olabilir. Sonuncusunun açıklamaya ihtiyacı var. Bazen platforma giden istek gönderilir ama yanıt geri gelmez ve platformun yanıtı geri okuyacak bir yolu yoktur. Tekrar denemek, aynı yanıtı işletmenin adıyla iki kez yayınlayabilir. Bu yüzden duruyoruz, durumu unknown olarak işaretliyoruz ve istemciye yeniden göndermeden önce platformu kontrol etmesini söylüyoruz. "Bilmiyoruz" diyen bir durum, bir tahminden daha faydalıdır.

Yanıt uzunluk sınırları, yanıt kuyruğa alınmadan önce platform bazında kontrol edilir: Google Business Profile'da 4.096 bayt, Google Play'de 350 karakter, eBay'de 80. Bir emoji tek karakter ama dört bayttır; bu yüzden karakter sınırları için kod noktalarını, bayt sınırları için baytları sayıyoruz.
Kararlı ID'ler ve tekilleştirme
Tekrarlanan kayıtlar, istemcilerin en önce fark ettiği hatadır. Kuralımız basit: her bağlayıcı her yorum için platformun kendi ID'sini döndürmeli ve veritabanında (location_id, external_id) üzerinde benzersiz bir indeks olmalı. Aynı yorumun ikinci senkronizasyonu bir güncellemedir, asla yeni bir ekleme değil. Konumlar da aynı şekilde çalışır: (connection_id, external_id) üzerinde benzersiz bir indeks vardır.
Zor olan şu ki "platformun kendi ID'si" her zaman mevcut değil:
- Etsy yorumlarının kendi ID'si yok. Her yorum tam olarak tek bir işleme ait olduğu için işlem ID'si aynı zamanda yorum ID'sidir.
- WordPress.org akışında yorum ID'si vermiyor. Her yorum bir forum konusu olduğu için konu slug'ını kullanıyoruz.
- Shopify App Store sayfası HTML'inde bir yorum içerik ID'si taşıyor. Ona güveniyoruz; bir sayfa yeniden tasarımının bunu değiştirebileceğinin farkında olarak.
- Google Play gerçek ID'lere sahip, ama API'si yalnızca son yedi günde oluşturulan ya da düzenlenen yorumları döndürüyor. Saklanan geçmiş bizimdir ve onu yeniden okuyamayız.
İstemciler platform ID'lerini asla birincil anahtar olarak görmez. Onlar tip önekli ve zamana göre sıralı gövdeli kendi ID'lerimizi alır (rev_01KJ…, loc_01KJ…, req_01KJ…). Önek, yanlış yere düşmüş bir ID'yi loglarda bariz kılar; sıralama da sayfalamaya yardım eder: imleç son öğenin zaman damgasını ve ID'sini kodlar, böylece yeni yorumlar gelirken sayfa sınırı yerinde kalır.
Yeniden bağlanma. Bir işletme bir hesabın bağlantısını keser ve bir hafta sonra yeniden bağlar. Yeni konumlar oluşturmak her yorumu ikişer kopya yapardı. Bunun yerine, 30 günden daha kısa süre önce bağlantısı kesilmiş ve aynı harici ID'ye sahip bir konum yeniden etkinleştirilir: aynı ID'ler, hiçbir yinelenen yorum yok.
Silinenler. Platformdan kaldırılan bir yorum basitçe görünmez olur. Kimse size haber vermez. 84 kaynağın 60'ında tüm geçmişi okuyabiliyoruz; bu yüzden geçmişi düzenli olarak yeniden okuyoruz (Google Business Profile için 25 günde bir — şartları, içeriği 30 günden fazla doğrulanmamış tutmamıza izin vermiyor; diğerlerinin çoğu için haftada bir) ve platformun artık döndürmediği yorumları deleted_at ile, ayrıca bir review.deleted webhook'u ile işaretliyoruz. Kilit güvence şu: bir okuma, bir zaman aşımı ya da bir sayfa sınırı nedeniyle erken kesildiyse, hiçbir şeyi işaretlemiyoruz. "Göremedim"i "silinmiş" saymak, gerçek yorumları silerdi. Google Play, yedi günlük penceresi yüzünden bu kapsamın dışında.
OpenAPI şemasına karşı sözleşme testi
Sözleşme, 18 yolu, 30 şeması ve 9 webhook olayı olan bir OpenAPI 3.1 belgesidir. İki tür test onu dürüst tutuyor.
İlki ucuzdur ve her commit'te çalışır: şemanın enum değerleri kodla tam olarak eşleşmelidir. Şemadaki platform ID'leri platform yapılandırmasındaki listeyle, şemadaki webhook olayları kodun üretebileceği olay türleriyle aynı olmalıdır. Üretilmiş istemciler bilmedikleri enum değerlerini reddeder; dolayısıyla koda eklenip şemaya eklenmemiş bir platform, bu istemcileri ilk senkronizasyonlarında bozar.
İkincisi bir test modudur. API anahtarları aynı sunucuya karşı iki türde gelir: pk_live_… ve pk_test_…. Bir test anahtarı her platformu bir test bağlayıcısına yönlendirir: gerçek olanlara benzer deterministik örnek konumlar ve yorumlar (Google'da bir kafe, App Store'da bir uygulama, Booking.com'da bir otel), hiçbir yerde yayınlanmayan kabul edilen yanıtlar ve salt okunur platformlarda her yorumda bir url — çünkü belgeler bunu vaat ediyor. Herkes, gerçek bir hesaba dokunmadan tüm sözleşmeyi, yazma yolları dahil, çalıştırabilir.
Aşağıdaki örnekler şemadaki örneklerdir; URL'ler example.com ile değiştirilmiştir. Bir listeleme isteği:
GET /v1/reviews?platform=google&limit=1
Authorization: Bearer pk_test_…daha önce gösterilen yorumu data içinde, ayrıca bir next_cursor ile döndürür. Yanıtları destekleyen bir platforma verilen yanıt 202 ile kabul edilir ve yorum, yanıtı kuyrukta olarak geri gelir (diğer alanlar atlanmıştır):
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
}
}İlginç durumlar hatalardır. Her hata aynı şekle sahiptir (type, code, message, retryable, request_id, docs_url) ve bazı kodlar istemcinin üzerine işlem yapabileceği ek alanlar taşır. Bir Yelp yorumuna yanıt vermek 422 döndürür:
{
"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"
}
}Platformun sınırını aşan bir yanıt da 422 döndürür; code: "reply_too_long", platform: "google_play" ve max_length: 350 ile. İstemciler dallanmayı message üzerinden asla, code üzerinden yapmalıdır: mesaj insanlar içindir ve değişebilir.
Aynı şekil canlı trafikte de geçerlidir. Bu, anahtarsız bir isteğe üretimden gelen gerçek bir yanıttır (başlıklar kırpılmış, docs URL'si değiştirilmiş):
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"}}Gövdedeki request_id, Request-Id başlığıyla eşleşir. Her işlem için durum kodunu, gövdenin kendi şemasına göre doğrulandığını (14 yorum alanının tamamı mevcut, nullable türler bildirildikleri yerde), her 2xx olmayan yanıtta hata şeklini ve başarı durumunda Request-Id ile hız sınırı başlıklarını kontrol ediyoruz.
Aynı kontrolleri Apidog CLI ile çalıştırın
Aynı kontroller, bir OpenAPI dosyasıyla gelen her API üzerinde çalışır. Apidog CLI şemayı içe aktarır ve Claude Code gibi bir kodlama ajanı test senaryolarını yazar ve çalıştırır. Bir kez kurun:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install
Sonra ajana tek bir prompt verin:
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.Ajan şemayı içe aktarır, test senaryosu şemasını okur, yükünü doğrular, senaryoyu oluşturur ve çalıştırır:
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 raporlayıcısı CI'ınızın okuyabileceği bir dosya yazar; böylece aynı çalıştırma her pull request'i bir kapı gibi kontrol edebilir. Apidog CLI CI/CD rehberi pipeline kurulumunu ele alıyor.
Öğrenilen dersler
"API'si var" ile "yanıt verebilir"i ayrı özellikler olarak modelleyin. Atlassian ve Microsoft, bir API'nin var olup yine de yanıt alamayabileceğini gösteriyor. İkisi için tek bir bayrak, teslim edemeyeceğimiz yanıtların vaadi olurdu.
İlk yanıt gönderilmeden önce unknown yanıt durumunu planlayın. Belirsizliği kabul eden bir durum yalnızca bir enum değeri kaybettirir; yinelenen herkese açık bir yanıt ise bir müşterinin güvenini kaybettirir.
Bir platform ID'sinin var olduğuna ya da kararlı kalacağına güvenmeyin. Her bağlayıcı için ID'nin nereden geldiğini ve neyin onu değiştirebileceğini yazın.
Şemayı koda karşı test edin, yalnızca kodu şemaya karşı değil. Enum testi yaklaşık on satırlıktır ve üretilmiş istemcileri en çok inciten hatayı korur.
