API versiyası strategiyaları

Niyə versiya lazımdır

API müştərilərdən daha sürətli dəyişir. Versiyalaşdırma, inteqrasiyanın pozulmaması, dəyişiklik ritualının təyin edilməsi və təkamülün proqnozlaşdırıla bilən olmasına imkan verir. Açar: default əlavə dəyişikliklər, majors - yalnız sınaqlar, avtomatik uyğunluq yoxlamaları və düşünülmüş sunset siyasəti üçün.

Əsas prinsiplər

1. Additive-first: yeni isteğe bağlı sahələr/metodlar/hadisələr - tamam; məna aradan qaldırılması və dəyişdirilməsi - major.
2. MGC (minimum zəmanət müqaviləsi) sabitdir; zənginləşdirmə - capabilities/'? include = 'vasitəsilə.
3. Tolerant reader: Müştərilər naməlum sahələrə məhəl qoymur və düzgün enum genişləndirmələrini yaşayırlar.
4. Semantic Versioning: `MAJOR. MINOR. Artefaktlar, SDK və hadisələr üçün PATCH '.
5. Automate: schema-diff, linters və CDC testləri breaking-dəyişiklikləri bloklayır.

Versiyanı harada saxlamaq olar (ünvanlama mexanikası)

REST/HTTP

URI versiyası: '/v1/orders '→ sadəcə marşrutlaşdırmaq, şlyuzlarda rahatdır. Mənfi - fikirlərin təkamülünü «maneə törədir».
Media/Başlıq: 'Accept: application/vnd. example. orders. v1 + json '- formatın dəqiq idarə edilməsi; mübahisə etmək daha çətindir.
Query versiyası: '? api-version = 1' - A/B üçün əlverişlidir, lakin caches/log-da itirmək asandır.
Tövsiyə: major-lines + feature/capability flags üçün URI və minor uzantıları üçün məzmun neqasiya.

gRPC / Protobuf

Paketlər/xidmətlər: 'package payments. v1; service PaymentsV1; '- açıq xətlər.
Etiketlərin nömrələnməsi dəyişməz; silinmiş etiketlər çox istifadə deyil.
Yeni sahələr - 'optional'; breaking → yeni '.v2'.

GraphQL

URL-də açıq major olmayan sxem. @deprecated və miqrasiya pəncərələri vasitəsilə təkamül; «real» major - yeni end-point sxemi.
Complexity/depth kontraktın bir hissəsidir.

Event-driven (Kafka/NATS/Pulsar)

Hadisə adı: 'payment. authorized. v1 '- tip versiyası.
Uyğunluq rejimləri ilə sxemlərin reyestri (Avro/JSON Schema/Protobuf) (BACKWARD/FORWARD/FULL).
Major → dual-emit 'v1' və 'v2' keçid dövrü üçün.

Versiya modeli və dəyişiklik siyasəti

Semantic Versioning

MAJOR - qırıcı dəyişikliklər: sahələrin silinməsi/adının dəyişdirilməsi, partizan açarlarının dəyişdirilməsi, statusların fərqli mənası, validasiyanın sərtləşdirilməsi.
MINOR - əlavə: yeni isteğe bağlı sahələr/enpoints/hadisələr, tolerant-reader-də yeni enum dəyərləri.
PATCH - müqavilə və semantika dəyişdirilmədən düzəlişlər.

Deprecation & Sunset

Köhnəlmiş ('Deprecated: true', '@deprecated') etiketləyin, sunset tarixini, alternativini və miqrasiya bələdçisini dərc edin.
HTTP-də - 'Sunset', 'Deprecation' başlıqları; hadisələrdə - ayrı '.deprecation. notice`.
Çıxarılması barədə qərar vermək üçün usage telemetriyasını edin.

Stillərə görə versiya strategiyaları

REST

Major xətləri/v1 ,/v2.
MINOR: sxemlərin genişləndirilməsi, '? fields =', '? include ='; təhlükəsiz enum uzantıları.
ETag/If-Match və idempotent POST heç bir qırılma uyğunluq üçün.
Səhvlər sabit formatdır ('type', 'code', 'trace _ id').

gRPC

Sındırma üçün yeni xidmətlər/metodlar təqdim edin: 'PaymentsV2. Capture`.
Səhv statusu və deadline semantikası müqavilənin bir hissəsidir; → yeni metod/xidmət dəyişdirmək.
Axın: Mesajların qaydası barədə razılığa gəlin və onu minora dəyişməyin.

GraphQL

Sərbəst sahələr və növlər əlavə edin; silinir - '@deprecated' + miqrasiya pəncərəsi vasitəsilə; böyük yenidən dizayn → yeni sxem ('/graphql-v2 ').
İntrospektsiya və təsvirlər - müştəri miqrasiyası üçün must-have.

Events

Core vs enriched: nüvə stabildir, zənginləşdirmə yaxınlıqda yaşayır və ayrıca versiyası.
Partizan açarı major xətti daxilində dəyişməz olaraq qalır.
Major-miqrasiya - 'dual-emit' + proyeksiyaların/konsumerlərin miqrasiyası.

Negotiation və capability bayraqları

Capabilities: müştəri göndərir 'X-Capabilities: risk_score,price_v2'; server geniş görünüşlə cavab verir.
Qismən cavablar üçün Prefer (HTTP) və «hints».
Soketlərdə/axınlarda - dəstəklənən uzantıların siyahısı ilə handshake mesajı.

Ağrısız major versiyalarının buraxılması

1. RFC/ADR: niyə major lazımdır, nə qırılır, risk matrisi.
2. Dual-run: paralel start 'v1' və 'v2' (hadisələrin ikiqat yayımı, iki gateway-rout, trafik güzgüsü).
3. Miqrasiya adapterləri: ağır müştərilər üçün proxy/translatorlar 'v1, v2'.
4. Kanarya: gateway-də müştəri qruplarına/topiklərə/etiketlərə görə.
5. Sunset planı: tarixlər, rabitə, stendlər, test məlumatları, istifadə monitorinqi.

Platforma və infrastrukturun rolları

API Gateway/Service Mesh: versiya, başlıqlar, yollar üzrə marşrutlaşdırma; rate-limit и auth per-version.
Schema Registry & Catalog: diff tarixi ilə spec/sxemlər üçün həqiqət mənbəyi.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observability: versiyası daxil olmalıdır/treys/metrik.

Test versiyası

PR Schema-diff: breaking bloklamaq.
Consumer-Driven Contracts: Provayder real istehlakçıların müqavilələrinə qarşı yoxlanılır.
Golden samples: versiyası üçün istinad cavabları.
E2E-kanarya: p95/p99, səhvlər və versiyalar arasında vaxtların müqayisəsi.
Hadisələr üçün replay: proyeksiyalar uyğunsuzluqlar olmadan v2-yə köçürülür.

Verilənlər və bazaların miqrasiyası

REST/gRPC üçün: BD miqrasiyaları expand-and-contract vasitəsilə əlaqələndirilir (→ yazmağa başla → oxu → köhnə oxu).
Events üçün: dual-emit və konsumer miqrasiyası; bəzən - yeni proyeksiyalar üçün log yenidən oynamaq.
«Böyük partlayışlar» etməyin - geri çəkilmə ilə addımları parçalayın.

Təhlükəsizlik əlaqəsi

Scopes per version: v1/v2 üçün ayrı-ayrı OIDC-scopes/rolları.
Sirləri/claim 's token - müqavilənin bir hissəsi; onların növbə = major.
PII/PCI - lazımsız payload genişləndirməyin; yeni sahələr - minimum imtiyazlarla.

Antipatternlər

Swagger-wash: spesifikasiyası yeniləndi, server - yox (və ya əksinə).
Protobuf etiketlərinin yenidən istifadəsi məlumatların sakit pozulmasıdır.
Major olmadan enum mənalarının dəyişdirilməsi.
Qlobal '/v2 '«kosmetika üçün»: qırılma faktı olmayan versiya.
Sunset/usage-metriklər unuduldu: köhnə versiyanı təhlükəsiz şəkildə çıxarmaq mümkün deyil.
Müxtəlif major üçün bir ümumi topik: sıraların və açarların qarışması.

Buraxılışdan əvvəl çek siyahısı

• Dəyişikliklər əlavə və ya ayrı bir major xətti hazırlanmışdır.
• Linters və schema-diff yaşıl (breaking keçilmədi).
• Yenilənmiş SDK/nümunələr/sənədlər, uyğunluq haqqında dipnotlar.
• Müştərilərdə tolerant reader daxildir; enum-fallback test edilmişdir.
• Major üçün - dual-run planı, adapterlər, kanarya, sunset tarixləri və poçt.
• Metrik/Logy/Treys onun versiyasını və seqmentini ehtiva edir.
• Müqayisə üçün stand və qızıl dəstləri var v1, v2.
• Hadisələr üçün - BACKWARD/FULL rejimində sxemlərin reyestri, partizan açarları dəyişməz olaraq.

Nümunə nümunələri

REST (URI + negotiation)

Marşrut: '/api/v2/orders/{ id} '

Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`

Deprecation: `Sunset: 2026-06-30`, `Link: ; rel="alternate"`

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Events

`payment. captured. v2 '(nüvə) və' payment. enriched. v2 '(detallar).
Keçid dövründə prodüserdən 'v1' və 'v2' gəlir.

FAQ

'/v2 'dəqiq nə vaxt lazımdır?
İnvariantlar/semantika dəyişdikdə, sahələr/metodlar silinir, identifikatorların formatı, partizan açarı, SLA/zamanlama müştərilərin pozulması üçün dəyişir.

REST-də aydın bir versiya olmadan yaşaya bilərəmmi?
Yalnız kiçik sistemlər üçün. Xarici inteqrasiya üçün - daha yaxşı açıq major xətləri.

Köhnəlmiş versiyanı saxlamaq üçün hansı müddət var?
Ekosistemdən asılıdır. Xarici tərəfdaşlar üçün adətən erkən bildiriş və kanarya ilə 6-12 ay.

Hadisələrin versiyası API-dən nə ilə fərqlənir?
Hadisələr - append-only; yeni semantika = yeni tip '.v2' və dual-emit. Partiyalaşdırma açarı müqavilənin bir hissəsidir.

Yekun

Version strategiyaları proses və alətlərdir: varsayılan additiv təkamül, aydın major xətləri, capability-negotiation, dual-run və sunset. Buna avtomatik uyğunluq yoxlamaları, istifadə telemetriyası və sənədləşmə intizamı əlavə edin - və API-ləriniz müştərilərdə «gecə köçləri» və gözlənilməz enişlər olmadan sürətlə inkişaf edəcəkdir.