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.
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.