API Versiyonlama & Deprecation
Eklenti sürümleme kuralları (semver), platform API'sinin uyumluluk sözleşmesi (neler kırıcı sayılır, neler sayılmaz) ve kırıcı değişikliklerin nasıl duyurulduğu. Entegrasyonunu bilinmeyen alanlara toleranslı kur — ileriye dönük uyumluluğun temeli budur.
Eklenti sürümleme (semver)
| Kural | Davranış |
|---|
| Format | MAJOR.MINOR.PATCH (örn. 1.4.2) — başka format kabul edilmez |
| Sıralama | Yeni sürüm, onaylı son sürümden BÜYÜK olmalı — downgrade engellenir (kayıt + onay anında doğrulanır) |
| Değişmezlik | Onaylanan sürüm değiştirilemez — düzeltme/yeni özellik = yeni sürüm numarası |
| Review | Her yeni sürüm kendi incelemesinden geçer; reddedilirse notlarla taslağa döner, düzeltip yeniden gönderirsin |
| Yeni scope | Sürümde yetki (scope) genişletmek inceleme sırasında ayrıca işaretlenir — özellikle PII scope'ları gerekçelendir |
Manifest alanları ve scope listesi için: Manifest Referansı · Scope Referansı.
Platform API uyumluluk sözleşmesi
Veri API'si ve webhook payload'ları eklemeli (additive) genişler. Aşağıdakiler kırıcı sayılmaz ve önceden duyurulmadan yapılabilir:
- Yanıtlara / event payload'larına yeni alan eklenmesi
- Yeni event tipi, yeni uç, yeni scope eklenmesi
- Yeni opsiyonel istek parametresi eklenmesi
Kırıcı sayılır (duyurusuz yapılmaz):
- Mevcut bir alanın kaldırılması/yeniden adlandırılması veya tipinin değişmesi
- Bir ucun/event'in kaldırılması, hata kodu sözleşmesinin değişmesi
- Önceden kabul edilen bir isteğin reddedilmeye başlanması (örn. yeni zorunlu doğrulama)
Toleranslı parser yaz: JSON'da tanımadığın alanları yok say (strict şema doğrulamasında bilinmeyen alanı hata yapma), tanımadığın event tipine 200 dön ve işlemeden geç. Böylece eklemeli değişiklikler entegrasyonunu hiç etkilemez.
Her kurulum, kurulum anında bir apiVersion sabitler (varsayılan "1") — bu, webhook zarfındaki version alanıdır. Platformun şema yükseltmeleri mevcut kurulumları kırmaz; her kurulum kendi sabitlenmiş sürümünden okumaya devam eder (Stripe/Shopify modeli).
Kırıcı değişiklik & deprecation süreci
- Kırıcı değişiklikler önceden Değişiklik Günlüğü'nde duyurulur ve etkilenen doküman sayfalarında not düşülür.
- Henüz yayında olmayan özellikler dokümanlarda "yakında" rozetiyle işaretlidir — rozetli bir uca/event'e üretimde güvenme; canlıya alınınca rozet kalkar ve changelog'a girer.
- Kullanımdan kaldırılacak (deprecated) davranışlar changelog'da geçiş notuyla duyurulur; mümkün olan durumlarda eski davranış bir geçiş penceresi boyunca korunur.
Entegrasyonun canlıdaysa
changelog'u takip et — kırıcı olabilecek her değişiklik orada işaretlenir.
En iyi pratikler
- Webhook/payload parse'ında bilinmeyen alan = yok say; enum benzeri alanlarda bilinmeyen değere güvenli varsayılanla davran.
- Event aboneliğini manifest'te ihtiyacın kadar tut — yeni event tipleri eklendikçe otomatik almazsın, bilinçli eklersin.
- Sürüm yükseltirken scope değişikliklerini sürüm notunda açıkla — inceleme hızlanır.
- Rate limit ve liste cap'leri için: Limitler & Kotalar.
- Canlıya geçerken: Yayına Alma (Go-Live) kontrol listesi.