Teknoloji ve Altyapı - API Versioning

API sürümleri

1) Neden ihtiyacınız var

• Serbest bırakma sırasında olay riskini azaltır,
• İyileştirmeleri ve güvenliği planlamanızı sağlar,
• İş ortağı geçişleri için işletmelere öngörülebilir zaman çizelgeleri sağlar.

2) Değişikliklerin sınıflandırılması

PATCH (kırılmıyor): sözleşmeyi değiştirmeden düzeltmeler (isteğe bağlı alanlar ekleme, doğrulama düzeltmeleri).
MINOR: geri uyumlu uzantılar (yeni uç noktalar, öntanımlı alanlar).
MAJOR (breaking): Yapı, semantik değiştirme veya alanları/uç noktaları silme.

SemVer 'MAJOR önerilir. MINÖR. Yapaylar için PATCH '(SDK/şemalar), "harici" API numarası basitleştirilebilir (v1, v2).

3) REST sürüm modelleri

1. URI'YE:

'GET/v1/payments/{ id}'

Artıları: şeffaf, cable, rota kolay. Eksileri: belgelerin çoğaltılması, ince bir şekilde gelişmesi daha zor.

2. Başlıklarda (içerik anlaşması):

'Accept: application/vnd. Şirket. ödemeler. V2 + json '

Artıları: esneklik, URL'de "çöp" yok, medya türünün uygun evrimi. Eksileri: Tarayıcıda hata ayıklamak daha zordur, disiplinli bir müşteriye ihtiyacınız vardır.

3. Özel başlıkta:

'X-API-Sürüm: 2' (или 'Api-Sürüm: 2025-09-01')

Artılar: Sadece sluice. Eksileri: standart yok, önbelleğe dikkat edin.

4. Tarih tabanlı sürüm:

Fintech/raporlama için iyi: değişimin öngörülebilir "kesintileri" (örn. Üç ayda bir).

5. Kaynak/Model Sürüm Oluşturma:

Öneri: dış entegrasyonlar için - 'URI vN' + Reddetme/Günbatımı başlıkları; Dahili için - ağ geçidi ve platform destekliyorsa, 'Kabul' veya sürüm başlığını kabul edebilirsiniz.

4) GraphQL

Tercih - global versiyon yok. Alanların/türlerin eklenmesi ve depriction ('@ kullanımdan kaldırıldı (sebep:... "")').
Değişikliklerin kırılması - yalnızca geçiş kılavuzuna sahip "büyük" pencerelerde (sürüm şeması ad alanı).
"N + 1'i izleyin ve mevcut alanların anlamını değiştirmeyin.

5) gRPC/Protobuf

Alan numaraları değişmez. Silinen alanları 'ayrılmış'olarak işaretleyin.
Alanları güvenli varsayılan değer ile isteğe bağlı olarak ekleyin.
Otomatik uyumluluk kontrolü için buf kırma/tiftik kullanın.
Sürüm paketleri/modülleri: 'paket ödemeleri. v1; '-' ödemeleri. v2 '.

6) Etkinlik API'leri (EDA)

Olay şeması aynı sözleşmedir. Şema Kayıt Defteri'nde saklayın (Avro/JSON-Schema/Protobuf).
Konular ve versiyonlar: 'ödemeler. v1. Yetkili ',' ödemeler. V2. yetkilendirildi '.
Değişiklikleri kırmak - yeni bir olay türü veya yeni bir konu.
Evrim garanti eder: LTS döneminde tüketiciler için geriye dönük uyumlu.

7) Depriction Politikası ve EOL

• Kullanım dışı bırakma: Değişiklik günlüğü ve özelliklerdeki etiketler (OpenAPI/GraphQL SDL), üstbilgi
• 'Depresyon: doğru've mümkün olduğunda' Sunset: Tue, 31 Mar 2026 00:00:00 GMT '.
• İletişim: e-posta/iş ortağı portalı, webhooks bildirimleri, sürüm notları.
• Şartlar: MINOR - 3-6 aylık destek, MAJOR - 9-18 ay (kritikliğe bağlı olarak).
• Zaman pencereleri: "API Sürüm Oluşturma İlkesi'nde düzeltin.

8) Yönlendirme ve Sürümler

Ağ Geçidi API'si (Kong/Apigee/Nginx/Envoy):'/v1/' önekine göre kurallar, başlık veya mediatype ile.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Kanarya/Mavi-Yeşil/Gölge: Yeni sürümü trafiğin %1-5'inde yuvarlayın, metrikleri ve sözleşme hatalarının günlüklerini karşılaştırın.
Özellik Bayrakları: Sözleşmeyi değiştirmeden davranışı gizleme.
Sıfır kesinti süresi geçişi: MAJOR ile veri şemasının çift yazılmasını/okunmasını sağlayın.

9) Sözleşme testi ve uyumluluk kontrolü

OpenAPI Diff (veya swagger-diff) - MINOR/PATCH'in şemaları kırmadığını kontrol edin.
Spektral çizgi oluşturma - stil, gerekli meta veriler (sürüm, Kullanımdan kaldırma).
Tüketici Odaklı Sözleşmeler (Pakt) - sağlayıcının müşterileri kırmamasını sağlar.
Buf kırma для protobuf.
CI MAJOR yükseltmeden değişiklikleri kırma düşmelidir.

10) Dokümantasyon ve SDK

Spesifikasyonların sürümü:'/docs/api/v1/openapi. json ','/docs/api/v2/...'.
SemVer ve changelog ile sürüm (npm/maven/pypi) tarafından SDK oluşturun.
SDK'da kullanımdan kaldırılmış yöntemleri/Kullanımdan kaldırılmış ek açıklamalarla işaretleyin.

11) Versiyona göre gözlem

• RPS/latency/errors per version ('api _ version' etiketi).
• Uç nokta kullanım haritaları: V1'de başka kimler var?
• Uyarılar: "> 10 %4xx sözleşme uyumsuzluğu nedeniyle",'eski müşteriler> T-tarihinden sonra % X ".

12) Önbelleğe alma ve sürümler

Transit versiyonu CDN cachability geliştirir.

• 'Vary: Accept, X-API-Version'.
• Önbellek anahtarlarını kırmak için MINOR'daki yanıtın semantiğini değiştirmeyin.

13) Güvenlik

Sürümü JWT'ye şifrelemeyin veya dikmeyin - sürüm, belirteç değil, istek tarafından belirlenir.
İç montaj numaralarını göstermeyin. Harici mesajlar için "v1/v2" kullanın.
MAJOR'da inceleme doğrulama, limitler, PII maskeleme.

14) Geçişler ve otomatik yardımcılar

"Geçiş Kılavuzu v1 - v2'yi yayınlayın: alan eşleme tablosu, örnek istekleri/yanıtları, kenar durumları.
Eski alanları vurgulayan müşteriler (CLI) için astarlar sunuyoruz.
Büyük ortaklar için - iki sürümü ve bir test veri kümesi ile sandbox.

15) Anti-desenler

"Ebedi v1": son teslim tarihlerinin ve kullanım metriklerinin eksikliği.
MINOR/PATCH'de gizli kırılma değişiklikleri.
"Sorgu dizesinde sürüm" ('? v = 2 ') - önbelleği ve okunabilirliği keser.
"Bir uç nokta yüz bayrak değeridir": test edilmesi/belgelenmesi zor.

16) Uygulama kontrol listesi

1. Dış ve iç istemciler için seçilen model (URI/Accept/Header).
2. Özellikler ve SDK için SemVer, CI'da otomatik kırma kontrolü.
3. Kullanımdan kaldırma/Günbatımı politikası ve iletişim şablonları.
4. Ağ geçidi yönlendirme + kanaryalar, versiyona göre panolar.
5. Kritik entegrasyonlar için CDC/Sözleşme testleri (ödemeler, KYC, raporlama).
6. Dokümantasyon/SDK/geçiş kılavuzu, sürüm ile aynı anda yayınlanır.
7. Tarihler ve sorumlu EOL planı.

17) Örnekler

17. 1 REST (URI + başlıkları)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 İçerik pazarlığı

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (Alan Depriksiyonu)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 Olay modeli

• 'wallet. v1. denge. güncellenmiş '
• 'wallet. V2. denge. changed '(genişletilmiş şemaya sahip yeni olay)

Şemalar Kayıt Defterinde saklanır, üretici uyumluluğu ihlal eden bir şemayla olayları yayınlamaz.

18) Bağlam iGaming/fintech (uygulama)

Ödemeler: 'Durum'/' düşüş _ nedeni'nin genişletildiği yeni PSP'ler için girdi v2; Ağ geçidinde, raporlama için v1 - v2 eşleniyor.
KYC: MINOR, 'pep _ screening' alanını ekler, müşteriler v1'i görmezden gelir, v2 - gerektirir.
Sorumlu oyunlar/limitler: MAJOR limitler modelini değiştirir (günlük/haftalık). EOL v1'den önce raporlamaya çift ihracat.
Düzenleyicilere raporlama: sabit sürümler-tarihler: 'raporlama-2025-01'.

19) Mini politika (wiki için örnek)

Model: harici API'ler için - 'URI/vN/'; Dahili için - 'Kabul:... vN + json 'veya' X-API-Sürüm: N '.
SemVer: Özellikler ve SDK'lar 'N'olarak yayınlanır. Minör. Yama '. MAJOR RFC/ADR gerektirir.
Uyumluluk: MINOR/PATCH - kırılma değişikliği yok. Sadece MAJOR ile kırma.
Amortisman/EOL: ≥90 günlük duyuru; Başlıklarda gün batımı-tarih; Kritik müşteriler için LTS şubesi.
Kontrol: Anahtar entegrasyonları için CI, CDC'de OpenAPI diff/buf kırma.
Gözlemlenebilirlik: 'api _ version' etiketli metrikler/günlükler.
Sürümler: kanarya %5 ≥ 24 saat, daha sonra yeşil metriklerle %100'e kadar aşamalar halinde.

Sonuç

Sürüm oluşturma "URL'de/v2'ile değil, süreçle ilgilidir: açık evrim kuralları, otomatik uyumluluk kontrolleri, yönetilen sürümler ve entegrasyonlara saygı. Net bir politika girin, izleme ve gözlemlenebilirliği otomatikleştirin - ve değişiklikler artık ürün için bir tehdit olmayacaktır.