Sürümleme ve uyumluluk
/v1 uyumluluk sözü, geriye dönük uyumlu ekleme kuralları, kırıcı değişiklik politikası ve yeni sürüm yolu, kullanımdan kaldırma, OpenAPI/SDK sürümleri ve değişiklik günlüğü.
Public API yolu /v1 altındadır ve geriye dönük uyumlu tutulur: mevcut entegrasyonlar sürüm yükseltmeden çalışmaya devam eder.
Ne uyumlu sayılır (duyurusuz yapılabilir)
- Yeni uç, yeni isteğe bağlı istek alanı, yeni sorgu parametresi.
- Yanıtlara yeni alan ekleme (istemciler bilinmeyen alanları yok saymalıdır).
- Yeni enum değeri yanıtlarda (ör. yeni
status, yenisuppression_reason, yeni webhook olay türü) — istemciler bilinmeyen değeri genel durumla ele almalıdır. oneOf/anyOfbirleşimlerine yeni varyant eklemek.- Hata
detailsnesnesine yeni alan; yeniHS_*kodu (HTTP durumu mevcut kurallara uyar).
Ne kırıcı sayılır (yeni sürüm yolu gerektirir)
- Alan/uç kaldırma ya da yeniden adlandırma, tür değiştirme, isteğe bağlı alanı zorunlu yapma.
- Mevcut
oneOfvaryantına zorunlu alan eklemek. - Kimlik doğrulama ya da hata zarfı biçimini değiştirmek.
Kırıcı değişiklikler /v2 altında yayımlanır; /v1 en az 12 ay desteklenir ve kullanımdan kaldırma tarihi önceden değişiklik günlüğünde duyurulur. Kullanımdan kaldırılan işlemler OpenAPI'de deprecated olarak işaretlenir ve referansta "kullanımdan kaldırıldı" rozetiyle görünür.
Sözleşme denetimi
api/openapi.yaml depoda sürümlenir; CI'daki sözleşme denetimi (npm run ci:local) her değişikliği önceki taban çizgisiyle karşılaştırır ve yalnızca ekleme olduğunu doğrular; bilinçli kırıcı değişiklik yeni sürüm + yeni taban çizgisi gerektirir. Üretilen sunucu SDK'ları (Python, Go, Java, .NET, Ruby) aynı sözleşmeden türetildiği için yeni uçlar tüm dillere aynı anda eklenir; yeniden adlandırılan SDK metotları eski adla kullanımdan kaldırılmış takma ad olarak korunur.
Sürüm numaraları
| Bileşen | Sürüm |
|---|---|
API sözleşmesi (info.version) | Platform sürümüyle aynı (semver; şu an 1.0.0) |
| Sunucu SDK'ları | Platform sürümünü izler; API_VERSION sabiti üretildiği sözleşmeyi söyler |
| İstemci SDK'ları | Kendi semver'leri; /sdk/v1 sözleşmesine bağlı |
| Webhook yükü | version alanı yok; olay yapısı yalnızca ekleme ile değişir, yeni olay türleri aboneliğe açıkça eklenir |
Kullanıcıya görünen tüm değişiklikler: API değişiklik günlüğü ve sürüm notları. Servis bilgisi ucu GET / çalışan sürümü döner.
Sayfalama, filtreleme ve sıralama
Cursor tabanlı listeleme (limit, cursor, next_cursor, has_more), cursor biçimi ve geçerliliği, filter[...] ve sort parametreleri, SDK'larda tüm sayfaları dolaşma yardımcıları.
Sistem ve sağlık
Sistem ve sağlık — 4 işlem (GET /, GET /status.json, GET /healthz, …). OpenAPI 3.1.0 sözleşmesinden üretilir.