Feedback Loop API ve sürüm geliştirme

1) Neden yönetilen bir Geri Bildirim Döngüsüne ihtiyacınız var?

Kırılma riskini azaltmak: Müşterilerden erken bir sinyal ve uyumsuzlukların otomatik olarak algılanması.
Benimseme büyümesi: Özellikler hipotezlere göre değil, gerçek senaryolara göre oluşturulur.
Sürümlerin öngörülebilirliği: sabit sürüm takvimi ve düşüşlerin şeffaf pencereleri.
Ekonomi: "Kırık entegrasyonlar" için daha az destek, daha düşük değişiklik maliyeti.

2) Geri bildirim kanalları (ve ağırlıkları)

Kullanım telemetrisi (uç noktalar/parametreler/hatalar bağlamında) gerçeğin ana kaynağıdır.
Müşterilerden/dahili ekiplerden RFC'ler - yapılandırılmış teklifler.
NPS/DevEx anketleri ve "entegratör görüşmeleri" yüksek kaliteli geri bildirimlerdir.
Sorunlar/forum/portal - sorunların hızlı alarmı.
Destek/Slack - metriklerde görünmeyen olay durumları.

3) Geribildirim Döngüsü mimarisi (veri akışları)

Producers (SDK/gateway/portal) - Kullanım ve Hata Veriyolu - DWH/Lake - Auto-Dif/Lint - Gösterge Tabloları ve Uyarılar - Yol Haritası/Backlog.

• Koleksiyon: çağrı sayaçları, parametreler, sürüm başlıkları, hata kodları, gecikme.
• Analitik: evlat edinme eğilimleri, ölü alanlar, sık sık 4xx/5xx, sürümlerle korelasyon.
• Sözleşme kontrolü: Şema-diff, CDC (tüketici odaklı sözleşmeler), API linter.
• Valilik: RFC/ADR, Yayın Konseyi, sürümlerin ve kararnamelerin takvimi.

4) Sürüm oluşturma politikası (SemVer + kanalları)

SDK/istemciler için SemVer: 'MAJOR. MINÖR. PATCH '.
API sürümleri: 'v1', 'v2' (breaking - major only). Minör - Uyumlu alanlar/uç noktalar ekleyin.
Tedarik kanalları: 'deneysel' - 'beta' - 'GA' - 'kullanımdan kaldırıldı' - 'gün batımı'.

Sürümün nerede saklanacağı

URL yolu:'/v1/... '- anlaşılabilir ve önbelleğe alınmış.

Başlık: 'X-API-Sürüm: 2025-11-03' - 'tarihli' sözleşmeler için

İçerik-Müzakere:'kabul: Uygulama/vnd. Acme. v1 + json '- ince granülasyon.
Bir birincil yöntem seçin, gerisi uyumluluk/geçişlerdir.

5) Uyumluluk ve "ekleme hakkı"

• İsteğe bağlı enum alanları/değerleri ekleyin (istemciler toleranslı-okuyucuysa).
• Varsayılan anlambilime sahip yeni uç noktalar/queri parametreleri.
• Sınırları/boyutları artırın (sözleşmeleri kaydederken).

• Alanları yeniden adlandırın/silin, türleri/formatları değiştirin.
• Zorunlu, anlamsal hataların/durumların değiştirilmesi.
• Müşteri mantığını etkileyen varsayılanları değiştirin.

Kural: daha az sihir, daha açık ("yeniden tanımlanmış" alanlar yerine yeni sürümler).

6) RFC/ADR süreci (özetlenmiştir)

1. Girişim (RFC) - motivasyon, kullanım durumları, etki, alternatifler.
2. Değerlendirme (kemer incelemesi) - güvenlik, uyumluluk, SLO, finops.
3. ADR: Sonuçları olan karar.
4. Tasarım Dondurma - prototip/ROS, sözleşme testleri.
5. Uygulama - özellik bayrakları, kanarya/beta kanalı, gözlemlenebilirlik.
6. GA - dokümantasyon/SDK/geçişler, SLO, destek.
7. Reddetme/Günbatımı - çekilme planı, araba sinyalleri, hatalar için SLA kredileri.

yaml rfc: RFC-0027 title: "Reports v2 cursor pagination"
motivation: "Offset causes drift at high churn"
breaking_change: false rollout: ["beta", "region=eu-west-1", "10% tenants"]
metrics: ["adoption_rate", "error_rate{status=422,429,5xx}", "latency_p95"]
migration: "v1=read-only 90d; dual-write v1/v2 30d"

7) Devreler ve otomatik diff (OpenAPI/AsyncAPI/Proto)

Tek kaynak: bilgi havuzundaki şemalar (monorepo veya sürüm kaydı).
Otomatik diff PR - bayrak "kırılır/kırılmaz"; Uyumsuz değişiklikler için kapıyı engelleme.
Linter: isimler/türler, kararlı 'error _ code', checkup pagination/idempotency.
CDC: tüketici sözleşmeleri (tüketici testleri) - CI'ye giriş; Kırmızı düğme - ihlaller.

yaml
- name: API Schema Diff run: api-diff --from main --to PR --fail-on=breaking --report artifact. json

8) Beta, kanarya, özellik bayrakları

Beta: opt-in kiracılar/anahtarlar, RPS/coğrafi kısıtlamalar.
Kanarya: % trafik veya istemci listesine göre, SLO sinyallerinde otomatik geri alma (hatalar/gecikme/429).
Özellik Bayrakları: dağıtımsız davranışı etkinleştirir/devre dışı bırakır; Yapılandırma servisinde depolayın, denetimi kaydedin.

9) Değer düşüklüğü ve gün batımı

Duyuru: changelog + portal, webhook'ların kullanımdan kaldırılması. notice," başlığı' Değer düşüklüğü: doğru'.
Pencere: Minimum 90-180 gün (kritikliğe bağlıdır).
İpuçları: cevaplarda 'Bağlantı: <...>; rel = "amortisman" 'и' Rel: "halef-sürüm" '.
Gözlemlenebilirlik: kontrol paneli "v1'de başka kim var? ", otomatik harfler/portal bildirimleri.
Sunset: Heading 'Sunset: 2026-03-31T00: 00: 00Z', son teslim tarihinden sonra, 410 Gone geri dönüyor.

json
{
"type": "deprecation. notice",
"api": "reports. v1",
"sunset_at": "2026-03-31T00:00:00Z",
"migrate_to": "reports. v2",
"guides": ["reports-v2-migration"],
"contact": "support@example. com"
}

10) Göçler ve versiyonların birlikte varlığı

Hareket süresince çift okuma/çift yazma; Raporlara karşı kontrol edilecek tutarlılık.
Eski istemciler için adaptörler (ince) sadece geçici bir önlemdir.
Geçiş kılavuzları: alan haritası, istek örnekleri, sık kullanılan tuzaklar.
SDK: Hem sürümler hem de "sapma uyarıları" (işlem başına 1 kez) desteği olan sürümler.
Test tezgahı: sandbox v2, düzeltmeler/veri üreteçleri.

11) Evrim başarı metrikleri

Benimseme oranı v2: Yeni sürümdeki trafiğin/istemcilerin %'si.
Kabul Etme Süresi: medyan geçiş süresi.
Geriye dönük compat olayları: kırılma numarası.
Hata karışımı: Serbest bırakıldıktan sonra 4xx/5xx paylaşımı, 422/429 ani artış.
DevEx: NPS/'ilk başarılı istek "zamanı.
Hizmet Maliyeti: Çağrı/rapor başına altyapı maliyeti.

12) Değişim Yönetimi ve Uyarılar

Pre-GA SLO: beta/kanarya için ayrı eşikler; Hızlı ve yavaş yanma kuralları.
Uyarılar: 5xx/latency spike, 422/429 yeni uç noktalarda yükselme, benimseme düşüşü.
Hata bütçeli yanma sırasında donmayı bırakın.

13) Dokümantasyon, portal, iletişim

Changelog с датами (eklendi/değiştirildi/kullanımdan kaldırıldı/kaldırıldı/düzeltildi).
Kılavuzlar: geçişler, örnekler, "kontrol listesini güncelle".
Portal: hizmet sürüm kartı, durumlar, gün batımı tarihi, v2 API sanal alanı, "erişim isteyin" düğmesi.
Comm paketi: postalar, RSS, portaldaki afişler, SDK sürüm notları.

14) Örnek sürüm politikası (alıntı)

yaml versioning:
strategy: "path"   # path    header    media compatibility:
minor: "additive-only"
patch: "bugfix/perf/no schema change"
deprecation:
min_notice_days: 120 comms: ["portal", "email", "status-webhook"]
rollout:
stages: ["exp", "beta", "ga"]
canary_policy:
step: [10,25,50,100]
checks: ["5xx_rate","p95_latency","429_rate","adoption"]

15) Tüketici Odaklı Sözleşmeler (CDC)

Sağlayıcı şemayı ve örnekleri yayınlar.
Tüketici, tedarikçinin CI'sında doğrulanan beklentileri (pact/hoverfly) saklar.
Kural: En az bir imzalı tüketiciyi kıran bir sürüm yayınlayamazsınız (geçiş penceresi karşılanmadıysa ve kabul edilmediyse).

16) Anti-desenler

"Sessiz" alan semantiği sürüm/dokümantasyon olmadan değişir.
Küçük sürümlerde gizli kırılma değişiklikleri.
Eski sürümler için sonsuz destek "sonsuza dek".
Evlat edinme metrikleri yoktur - eski sürümü kapatamazsınız.
Gereksiz SDK büyüsü sözleşmeye yansımaz.
Dağınık şemalar (kaynak bir değildir).

17) Yeni MINOR/MAJOR Sorun Kontrol Listesi

• RFC'ler/ADR'ler onaylandı; Güvenlik/finops/gözlemlenebilirlik değerlendirildi.
• Sicildeki şemalar; astarlar yeşil; Otomatik diff kırılma göstermez (MINOR için).
• Beta bayrakları; kanarya planı; SLO по otomatik geri alma.
• Dokümantasyon/SDK/örnekler güncellendi; Göç rehberi hazır.
• Portal: sürüm kartı, azaltma/erişim afişi.
• İletişim planı (posta listesi, durum web kitapları) ve gün batımı tarihi.
• Benimseme/hata panoları; uyarılar yapılır.
• Yasal/sözleşme şartları (SLA/faturalandırma değişirse).

18) Uygulama planı (3 yineleme)

Yineleme 1 - Temel (2 hafta)

Uç noktalara ve sürümlere göre kullanım/hata telemetrisini etkinleştirin.
Kayıt defterinde şemalar oluşturun, CI'da tiftik ve otomatik diff'i yapılandırın.
Sürüm politikası ve indirimleri tanımlayın; Portalda yayınlayın.

Yineleme 2 - Yönetilen Sürümler (3-4 hafta)

Bir RFC/ADR işlemi, özellik bayrakları ve otomatik geri alma ile kanarya/beta uygulayın.
CDC, CI sağlayıcısındaki önemli tüketicileri test eder.

Panoların benimsenmesi/hataları, iletişim şablonları ve webhook'ların depresyonu. Uyarı"

Yineleme 3 - Ölçek ve Otomasyon (Sürekli)

Diyagramlardan otomatik SDK/dock üretimi; Treni serbest bırakın.
Çok sürümlü sanal alan; Göçler için çift yazma.
Kabul eğilimine göre gün batımı tarihini tahmin etmek; otomatik hatırlatıcılar.

19) Mini-SSS

Herhangi bir rahatsızlık için her zaman majör bumpate yapmam gerekiyor mu?
Hayır. Değişiklikler eklemeli ve mevcut müşterileri kırmıyorsa - MINOR. Sadece uyumsuzluklar için MAJOR.

Tarih versiyonu mu yoksa 'v2'mi?
'v2' dokümantasyon ve önbellekler için daha basittir. Tarihli başlıklar "yumuşak" uyumsuzluklar ve A/B için uygundur.

V1'i kapatmanın zamanı geldiğini nasıl anlarsınız?
Benimseme v2> %95, v1'de kritik istemci yok, azaltma penceresi devam ediyor, hatalar/v1 desteği minimum düzeyde.

Toplam

Güçlü bir API öngörülebilir bir şekilde gelişir: telemetri ve CDC riskleri yakalar, RFC/ADR'ler şeffaf çözümler sunar, kanarya/beta hata maliyetini azaltır ve net bir sürüm ve azaltma politikası değişiklikleri müşteriler için güvenli hale getirir. Tek bir devre kaynağını düzeltin, diff/tiftik ve iletişimi otomatikleştirin, benimsemeyi ölçün - ve sürümleriniz entegratörleri "kırmayı" durduracak ve ürün geliştirme hızı artacaktır.