API Feedback Loop və təkamül versiyası

1) Niyə idarə Feedback Loop lazımdır

Sınma riskinin azaldılması: müştərilərdən erkən siqnal və uyğunsuzluq avtomatik detekti.
Adoption artımı: Fiçlər hipotezlərə deyil, real ssenarilərə əsaslanır.
Buraxılışların proqnozlaşdırılması: Sabit versiya təqvimi və şəffaf deprekasiya pəncərələri.
İqtisadiyyat: az dəstək «sınıq inteqrasiya», aşağı dəyər dəyişikliklər.

2) Rəy kanalları (və onların çəkisi)

Telemetriya istifadəsi (end-point/parametrlər/səhvlər baxımından) həqiqətin əsas mənbəyidir.
RFC müştərilərdən/daxili komandalardan - strukturlaşdırılmış təkliflər.
NPS/DevEx sorğuları və «inteqrator müsahibələri» - keyfiyyətli rəy.
Issues/forum/portal - problemlər haqqında sürətli siqnalizasiya.
Support/Slack - metriklərdə görünməyən insident halları.

3) Feedback Loop memarlığı (məlumat axını)

Producers (SDK/şlyuz/portal) → Usage & Error Bus → DWH/Lake → Auto-dif/lint → Dashboard & Alert → Roadmap/Backlog.

• Toplama: zəng sayğacları, parametrlər, versiya başlıqları, səhv kodları, latency.
• Analitika: adoption trendləri, «ölü» sahələr, tez-tez 4xx/5xx, relizlərlə korrelyasiya.
• Müqavilələrə nəzarət: schema-diff, CDC (consumer-driven contracts), API linter.
• Governance: RFC/ADR, Release Council, versiyalar və deprekasiya təqvimi.

4) Version siyasəti (SemVer + kanallar)

SDK/müştərilər üçün SemVer: 'MAJOR. MINOR. PATCH`.
API versiyaları: 'v1', 'v2' (sındırıcı - yalnız major). Minor - uyğun sahələr/end nöqtələri əlavə edin.
Təchizat kanalları: 'experimental' → 'beta' → 'GA' → 'deprecated' → 'sunset'.

Versiyanı harada saxlamaq olar

URL yolu: '/v1/... '- aydın və önbelleğe alınır.
Başlıq: 'X-API-Version: 2025-11-03' - «tarixli» müqavilələr üçün.
Content-Negotiation: `Accept: application/vnd. acme. v1 + json '- nazik qranulyasiya.
Bir əsas yol seçin, qalan - uyğunluq/miqrasiya.

5) Uyğunluq və «əlavə etmək hüququ»

• Enum (müştərilər tolerant-reader olarsa) isteğe bağlı sahələr/dəyərlər əlavə edin.
• Defolt semantikası ilə yeni end/query parametrləri.
• Limitlərin/ölçülərin artırılması (müqavilələr saxlanıldıqda).

• Sahələrin adının dəyişdirilməsi/silinməsi, növlərin/formatların dəyişdirilməsi.
• Məcburi dəyişiklik, səhv/status semantikası.
• Müştərinin məntiqinə təsir edən defoltların dəyişdirilməsi.

Qayda: Daha az sehr, daha çox aşkarlıq («yenidən müəyyən edilmiş» sahələr əvəzinə yeni versiyalar).

6) RFC/ADR prosesi (toplu)

1. Təşəbbüs (RFC) - motivasiya, use-cases, təsir, alternativlər.
2. Qiymətləndirmə - təhlükəsizlik, uyğunluq, SLO, finops.
3. ADR - nəticələri ilə qəbul edilmiş qərar.
4. Design Freeze - prototip/ROS, müqavilə testləri.
5. Realizasiya - Ficha bayraqları, canary/beta kanalı, müşahidə.
6. GA - sənədləşmə/SDK/miqrasiya, SLO, dəstək.
7. Deprecation/Sunset - çıxarış planı, avtosiqnallar, səhv olduqda SLA kreditləri.

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) Sxemlər və avto-dif (OpenAPI/AsyncAPI/Proto)

Vahid mənbə: anbardakı sxemlər (monorepo və ya versioned registry).
Avto-dif PR → bayraq «qırır/qırmır»; uyğun olmayan dəyişikliklər üçün kilidləmə qapısı.
Linter: adlar/tiplər, sabit 'error _ code', paqinasiya/idempotentlik çeki.
CDC: İstehlakçı müqavilələri (consumer tests) - CI-yə giriş; → «qırmızı düymə» pozuntuları.

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

8) Beta, canary, feature flags

Beta: opt-in tenants/açarları, RPS/geo məhdudiyyətləri.
Canary:% trafik və ya müştəri siyahısı, SLO siqnalları avtomatik geri (səhvlər/gecikmə/429).
Feature Flags: deploi olmadan davranışı açır/söndürür; -servisdə saxlayın, auditi qeyd edin.

9) Deprekasiya və sunset

Elanlar: changelog + portal, vebhuk "deprecation. notice", başlığı' Deprecation: true'.
Pəncərə: minimum 90-180 gün (kritik asılıdır).
İpuçları: cavablarda 'Link: <...>; rel="deprecation"` и `Rel: "successor-version"`.
Müşahidə müddəti: dashboard "v1 daha kim? ", avto məktublar/portal notifikasiyaları.
Sunset: Başlıq 'Sunset: 2026-03-31T00: 00: 00Z', müddətdən sonra - 410 Gone geri.

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) Miqrasiya və versiyaların birgə mövcudluğu

Hərəkət zamanı Dual-read/Dual-write; tutarlılığı hesabatlarla müqayisə edin.
Köhnə müştərilər üçün adapterlər (thin) yalnız müvəqqəti tədbirdir.
Miqrasiya qaydaları: sahə xəritəsi, sorğu nümunələri, tez-tez tələlər.
SDK: Hər iki versiya və «deprecation warnings» (hər proses üçün 1 dəfə) dəstəklənən buraxılışlar.
Test stendi: qum qutusu v2, fikstura/məlumat generatorları.

11) Təkamülün uğurunun metrikası

Adoption rate v2: yeni versiyada% trafik/müştərilər.
Time-to-Adopt: median miqrasiya vaxtı.
Backward-compat incidents: «qırılma» sayı.
Error mix: buraxıldıqdan sonra 4xx/5xx payı, 422/429 sıçrayışlar.
DevEx: NPS/« ilk uğurlu sorğu »vaxtı.
Cost-to-Serve: çağırış/report üçün infrastruktur dəyəri.

12) Dəyişikliklər və alertlərin idarə edilməsi

Pre-GA SLO: beta/canary üçün ayrı-ayrı eşiklər; sürətli və yavaş burn qaydaları.
Alerts: 5xx/latency sıçrayış, yeni end nöqtələrində 422/429 artım, adoption düşməsi.
Release freeze yanan error-budget.

13) Sənədləşmə, portal, kommunikasiyalar

Changelog с датами (added/changed/deprecated/removed/fixed).
Guides: miqrasiya, nümunələr, «çek yeniləmə siyahısı».
Portal: xidmət versiyası kartı, statuslar, tarix sunset, API qum qutusu v2, «giriş tələb et» düyməsi.
Komm paketi: poçt, RSS, portalda banner, SDK release notes.

14) Version siyasətinin nümunəsi (çıxarış)

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) Consumer-Driven Contracts (CDC)

Təchizatçı sxem və nümunələri dərc edir.
İstehlakçı CI təchizatçısında təsdiqlənən gözləntiləri (pact/hoverfly) saxlayır.
Qayda: Ən azı bir imzalı istehlakçını qıran bir versiya buraxmaq olmaz (miqrasiya pəncərəsi yerinə yetirilmədikdə və razılaşdırıldıqda).

16) Anti-nümunələr

versiya/sənədləşdirmə olmadan sahə semantikasında «sakit» dəyişiklik.
Minor relizlərdə gizli breaking-changes.
Köhnə versiyaların sonsuz dəstəyi «əbədi».
Metrik adoption → köhnə versiyanı bağlaya bilməz.
Müqavilədə əks olunmayan həddindən artıq SDK sehri.
Dağınıq sxemlər (mənbə bir deyil).

17) Yeni MINOR/MAJOR buraxılış çek siyahısı

• RFC/ADR təsdiq; təhlükəsizlik/finops/müşahidə qiymətləndirilir.
• registry sxemləri; yaşıl linterlər; auto-diff breaking göstərmir (MINOR üçün).
• Beta bayraqlar; canary planı; auto-rollback по SLO.
• Sənədlər/SDK/nümunələr yeniləndi; miqrasiya bələdçisi hazırdır.
• Portal: kart versiyası, deprekasiya/giriş banner.
• Comm Plan (poçt, status webhook) və tarix sunset.
• Dashboard adoption/səhvlər; alertlər açılır.
• Legal/müqavilə şərtləri (əgər SLA/billing dəyişir).

18) Tətbiq planı (3 iterasiya)

İterasiya 1 - Təməl (2 həftə)

Son nöqtələr və versiyalar üzrə istifadə/səhv telemetriyasını işə salın.
Sxemləri registriyaya daxil edin, CI-də lint və auto-diff qurun.
Versiyalar və deprekasiya siyasətini müəyyən edin; portalda dərc etmək.

İterasiya 2 - Idarə olunan buraxılışlar (3-4 həftə)

RFC/ADR prosesini, canary/beta ficha bayraqları və auto-rollback ilə tətbiq edin.
CI təchizatçı əsas istehlakçı CDC testlər.
Daşbordlar adoption/səhvlər, komm şablonları və vebhukları "deprecation. notice».

İterasiya 3 - Miqyas və avtomatlaşdırma (davamlı)

sxemlərdən SDK/Dock Avtomatik Generation; Release qatar.
Çox versiyalı qum qutusu; miqrasiya üçün dual-write.
Adoption trendinə görə sunset tarixinin proqnozlaşdırılması; auto remainders.

19) Mini-FAQ

Hər hansı bir narahatlıq zamanı həmişə major bumpor lazımdır?
Yox. Dəyişikliklər əlavə və mövcud müştəriləri pozmasa - MINOR. MAJOR yalnız uyğunsuzluqlar üçün.

Tarix versiyası və ya 'v2'?
'v2' sənədləşmə və cache üçün daha asandır. Tarixli başlıqlar «yumşaq» uyğunsuzluqlar və A/B üçün əlverişlidir.

v1-i bağlamağın vaxtı gəldiyini necə başa düşmək olar?
Adoption v2> 95%, v1-də kritik müştərilər yoxdur, deprekasiya pəncərəsi saxlanılır, səhvlər/dəstək v1 → minimaldır.

Yekun

Güclü API proqnozlaşdırıla bilər inkişaf edir: telemetriya və CDC riskləri tutur, RFC/ADR şəffaf həllər verir, canary/beta səhvlərin qiymətini aşağı salır və dəqiq versiya və deprekasiya siyasəti dəyişiklikləri müştərilər üçün təhlükəsiz edir. Vahid sxem mənbəyini düzəldin, dif/lint və kommunikasiyaları avtomatlaşdırın, adoption ölçün - və buraxılışlarınız inteqratorları «sındırmağı» dayandıracaq və məhsulun inkişaf sürəti artacaq.