API uyğunluğu və yeniləmələr
1) Uyğunluğun əsas prinsipləri
Additive-first: köhnəni qırmadan yenisini əlavə edin (yeni opsion sahələri/enpointlər, yeni enum dəyərləri).
Sabit müqavilələr: «spesifikasiyada vəd olunanlar işləyir»; davranış sənədləşdirilmişdir.
Backward> Forward: geri uyğunluq prioriteti; forward tolerant-readers vasitəsilə icazə verilir.
Sənədlər birincidir: həqiqətin yeganə mənbəyi registry (OpenAPI/AsyncAPI/Proto) sxeminin versiyasıdır.
Aydın təkamül: breaking - yalnız yeni major versiyası və miqrasiya bələdçisi vasitəsilə.
2) Dəyişikliklərin taksonomiyası
2. 1 Uyğun (MINOR/PATCH)
Opsiyonel sahələrin/hederlərin, yeni end nöqtələrinin, defolt query parametrlərinin əlavə edilməsi.
Limitlərin artırılması ('page _ size', TTL), kodlar/semantika dəyişdirilmədən səhvlərin dəqiqləşdirilməsi.
Müştərilər «tanımadığınız» (tolerant-reader) görməməzlikdən gəldikdə enum dəyərlərinin əlavə edilməsi.
2. 2 Qarışıq (Behavioral)
Defoltların, çeşidləmə qaydalarının, incə taymautların, kvotaların dəyişdirilməsi biznes məntiqini «poza» bilər. RFC + elanları və kanaryaları tələb edir.
2. 3 Sındırıcı (MAJOR)
Sahələrin adının dəyişdirilməsi/silinməsi, növün/formatın dəyişdirilməsi, səhv kodlarının dəyişdirilməsi, müqavilələrin/autentifikasiya sxemlərinin əks uyğunsuzluğu.
3) Version siyasəti
Strategiya: 'path versioning' ('/v1 ', '/v2').
Minor/patch: «əlavə edin, sındırmayın».
Tarixi başlıqlar (əlavə): yumşaq tədricən dəyişikliklər üçün 'X-API-Version-Date'.
Media növləri (ops.) : `Accept: application/vnd. acme. v1 + json 'nazik qranulyasiya üçün.
4) Deprekasiya və sunset
4. 1 Kommunikasiya başlıqları
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 Çıxış qaydası
1. Portalda elan/poçt/SDK release notes.
2. Xəbərdarlıq pəncərəsi 90-180 gün ≥.
3. Daşbordda statuslar adoption.
4. Sunset sonra - 410 Gone və ya «read-only» rejimi razılaşdırıldıqda grace dövrü üçün.
5) Miqrasiya və birgə varlıq versiyası
Keçid dövründə dual-write/dual-read və hesabatların müqayisəsi.
Adapterlər (müvəqqəti): köhnə payload → yeni sxemləri gateway çevirmək; adapter ömrü məhduddur.
SDK-yardım: Deprekasiya xəbərdarlığı ilə hər iki versiyanı dəstəkləyən buraxılışlar (hər proses üçün 1 dəfə).
Ficha bayraqları: açarlar/tenantlar siyahısı üzrə yeni semantikanın daxil edilməsi.
6) Backward və forward uyğunluq
6. 1 Backward (köhnə müştərilər yeni server)
Növlərin formatlarını/məcburiyyətini dəyişdirməyin.
Yeni sahələr yalnız seçimdir.
Səhvlər əvvəlki 'error _ code', yeni kodlar əlavə etmək, əvəz etmək deyil.
6. 2 Forward (köhnə server yeni müştərilər)
'OPTIONS '/'/versions' vasitəsilə imkanları (capabilities) yoxlayın.
Grace davranış: müştəri itkin fich dözümlü olmalıdır.
7) Müqavilələr və avtomatik yoxlamalar
Registry: sxemlərin versiyalarını saxlayırıq; PR-difs → hesabatlar «breaking/non-breaking».
Linter: adlar/tiplər, idempotentlik, paginasiya, sabit kodlar.
CDC (Consumer-Driven Contracts): CI təchizatçı inteqrator testlər (Pact və analoqları).
Gates: PR 'major bump '/RFC olmadan breaking zaman bloklanır.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Kanarya buraxılışı və geriyə
Canary: 10% → 25% → 50% → 100% trafik; SLO pisləşdikdə avtomatik geri çəkilmə (5xx/latency/429).
Beta açarları: allowlist üzrə yeni versiyalara çıxış.
Release freeze: error-budget yanması zamanı.
Qəbul analitikası: yeni versiyada trafik/müştərilərin payı, miqrasiya vaxtı.
9) Detallarda uyğunluq: səhvlər, paginasiya, idempotentlik
9. 1 Səhvlər
Mövcud ssenarilərdə HTTP statuslarını dəyişməyin.
'error _ code' - sabit; yeni kodlar yalnız əlavə.
'application/problem + json' - vahid format.
9. 2 Paginasiya
Köhnə 'offset/limit' dəstəklənərsə, cursor/keyset = MINOR-a keçid.
'(updated_at,id)' sıralamasını və kursorun sabitliyini sənədləşdirin.
9. 3 Idempotency
write üçün - 'Idempotency-Key' + '409 IDEMP_REPLAY' münaqişə zamanı.
Miqrasiyalar idempotentlik semantikasını dəyişdirməməlidir.
10) Gateway-transformasiya (uyğun olduqda)
Map v1 → v2 sahələri, səhvləri normallaşdırmaq, tarix/pul formatlarını çevirmək.
Guardrails: transformasiya şəffaf və loged; breaking gizlətməyin, lakin məhdud vaxt körpüsü kimi istifadə edin.
11) Rabitə və portal
Changelog с датами (`added/changed/deprecated/removed/fixed`).
Versiya kartı: status (beta/GA/deprecated), tarix sunset, qaydalara bağlantılar.
Bildiriş vebhukları: 'deprecation. notice`, `version. released`, `plan. change`.
SDK release notes + portalda banner.
12) Uğur metrikası
Adoption rate v2 (sorğu/müştərilər).
Backward-compat incidents («qırılma» sayı).
Error mix (4xx/5xx/429 payları) buraxılışdan əvvəl/sonra.
Time-to-Adopt media.
Support load (biletlər/həftə).
Cost-to-Serve (çağırış üçün infrastruktur dəyəri).
13) Nümunələr və nümunələr
13. 1 Versiyalar və Depreksiya Başlıqları
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Versiya siyasəti (YAML fraqmenti)
yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]13. 3 OpenAPI: uyğun sahə əlavə
yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive14) Buraxılış çek siyahısı (MINOR/MAJOR)
MINOR
- DIFF: qeyri-breaking, yaşıl linter
- Sənədlər/SDK yeniləndi (nümunələr/codec)
- Kanarya + SLO ilə avtomatik geri dönüş
- Komm planı, portalda səhifə
- Dashboard adoption və səhvlər
MAJOR
- RFC/ADR, tarix sunset və pəncərə ≥ 90-180 gün
- v1 v2 körpü (gateway) və miqrasiya bələdçisi
- Dual-write/oxumaq və yoxlama
- SDK hər iki API + xəbərdarlıqları ilə
- Əsas inteqratorlarla pilot
15) Tətbiq planı (3 iterasiya)
1. Təməl (2 həftə):
CI sxemləri, lint və auto-diff qeydiyyatı; uyğunluq siyasəti; başlıqlar 'Deprecation/Sunset'.
2. Idarə olunan buraxılışlar (3-4 həftə):
Kanaryalar, fiça bayraqları, SLO-alertlər; versiyalar portalı; 2 filialları dəstəkləyən SDK buraxılışları.
3. Avtomatlaşdırma və miqyas (davamlı):
CI-də CDC istehlakçı testləri, adoption tendensiyaları üçün sunset proqnozu, avtomatik qeydlər və xatırlatmalar.
16) Mini-FAQ
Sahə növünü major olmadan dəyişə bilərəmmi?
Yox. Hətta «sətir → nömrə» - fasilə. Yeni bir sahə daxil edin, köhnə - deprecate.
Enum: mənalar əlavə edə bilərəmmi?
Bəli, əgər müştərilər tolerant-readers. Əks halda - ilk xəbərdarlıq və beta.
Köhnə versiyanı nə qədər saxlamaq lazımdır?
İndiyə qədər yeni ≥ adoption 95% və deprekasiya pəncərəsi saxlanılır. Siyasətdə vaxtı təyin edin.
Yekun
API uyğunluğu intizamdır: additive-yanaşma, formal sxemlər və diflər, kanarya relizləri, aydın depreksiya və idarə olunan miqrasiyalar. Dəyişiklik siyasətini düzəldin, yoxlamaları və kommunikasiyaları avtomatlaşdırın, adoption ölçün - və yeniləmələriniz müştəriləri sındırmağı dayandıracaq və təkamül sürəti etibarlılığı itirmədən artacaq.