Texnologiya və infrastruktur → API versiyası

API versiyası

1) Niyə lazımdır

• buraxılış zamanı insident riskini azaldır,
• planlaşdırılan təkmilləşdirmə və təhlükəsizlik tətbiq imkan verir,
• biznesə tərəfdaşların miqrasiyasının proqnozlaşdırıla bilən müddətlərini verir.

2) Dəyişikliklərin təsnifatı

PATCH (pozulmayan): müqaviləni dəyişdirmədən düzəlişlər (isteğe bağlı sahələrin əlavə edilməsi, validasiya fiksləri).
MINOR (genişləndirici): back-compatible uzantıları (yeni end-point, default ilə sahələr).
MAJOR (qırıcı): strukturu, semantikasını dəyişdirmək və ya sahələri/end nöqtələrini çıxarmaq.

SemVer 'MAJOR tövsiyə olunur. MINOR. Artefaktlar üçün PATCH '(SDK/sxemlər), API «xarici» nömrəsi sadələşdirilə bilər (v1, v2).

3) REST versiyası modelləri

1. URI-DƏ:

`GET /v1/payments/{id}`

Üstünlüklər: şəffaf, cached, asan marşrutlaşdırmaq. Mənfi cəhətləri: sənədlərin təkrarlanması, incə inkişaf etmək daha çətindir.

2. Başlıqlarda (content negotiation):

`Accept: application/vnd. company. payments. v2+json`

Üstünlüklər: çeviklik, URL-də «zibil» olmaması, mediatipin rahat təkamülü. Mənfi cəhətləri: brauzerdə debat etmək daha çətindir, intizamlı bir müştəri lazımdır.

3. Xüsusi başlıqda:

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

Üstünlüklər: sadəcə şlüzdə. Dezavantajları: standart yoxdur, cache ilə diqqətli olun.

4. Versiya-tarix (date-based):

Fintech/hesabat üçün yaxşıdır: dəyişikliklərin proqnozlaşdırıla bilən «kəsikləri» (məsələn, rüblük).

5. Resurs/model versiyası:

Tövsiyə: xarici inteqrasiya üçün - 'URI vN' + Deprecation/Sunset başlıqları; daxili üçün - «Accept» və ya başlıq versiyası, əgər şluz və platforma bunu dəstəkləyir.

4) GraphQL

Üstünlük - qlobal versiyaları olmadan. Sahələrin/növlərin əlavə edilməsi və deprikasiya yolu ilə təkamül ('@deprecated (reason: «»...)').
Sındırıcı dəyişikliklər - yalnız miqrasiya bələdçisi olan «böyük» pəncərələrdə (versioned schema namespace).
«n + 1» və mövcud sahələrin meaning dəyişməmək üçün.

5) gRPC / Protobuf

Sahə nömrələri dəyişilməzdir. Uzaq sahələri 'reserved' kimi qeyd edin.
Təhlükəsiz default ilə optional olaraq sahələr əlavə edin.
Avtomatik uyğunluq testi üçün buf breaking/lint istifadə edin.
Paketləri/modulları versiya edin: 'package payments. v1;` → `payments. v2`.

6) Hadisə API (EDA)

Hadisə sxemi - eyni müqavilə. Onu Schema Registry-də saxlayın (Avro/JSON-Schema/Protobuf).
Topiklər və versiyalar: 'payments. v1. authorized`, `payments. v2. authorized`.
Sındırıcı dəyişikliklər - yeni bir hadisə növü və ya yeni bir topik.
Təkamül zəmanətləri: LTS dövründə konsumerlər üçün backward-compatible.

7) Deprikasiya siyasəti və EOL

• Deprecation: changelog və spesifikasiyalardakı etiketlər (OpenAPI/GraphQL SDL), başlıq
• 'Deprecation: true' və mümkün olduqda 'Sunset: Tue, 31 Mar 2026 00:00:00 GMT'.
• Rabitə: partnyor email/portalı, webhooks-bildirişlər, release notes.
• Vaxtlar: MINOR - 3-6 ay dəstək, MAJOR - 9-18 ay (kritik asılıdır).
• Müvəqqəti pəncərələr: "API Version Politics 'də qeyd edin.

8) Marşrutlaşdırma və buraxılışlar

API Gateway (Kong/Apigee/Nginx/Envoy): prefiks qaydaları '/v1/', başlıq və ya media ilə.

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

Canary/Blue-Green/Shadow: 1-5% trafikin yeni versiyasını yuvarlayın, metrikləri və müqavilə səhvlərinin qeydlərini müqayisə edin.
Feature Flags: müqaviləni dəyişdirmədən davranışı gizlədirik.
Sıfır-downtime miqrasiyası: MAJOR ikiqat qeyd/oxu (dual-write/read) məlumat sxemi təmin edin.

9) Müqavilə-test və uyğunluq nəzarəti

OpenAPI Diff (və ya swagger-diff) - MINOR/PATCH-in sxemləri pozmadığını yoxlayın.
Spectral linting - stil, məcburi metadata (versiya, Deprecation).
Consumer-Driven Contracts (Pact) - provayderin müştəriləri sındırmamasına zəmanət verir.
buf breaking для protobuf.
CI MAJOR-un artırılması olmadan pozucu dəyişikliklər zamanı düşməlidir.

10) Sənədləşmə və SDK

Species versiyası: '/docs/api/v1/openapi. json`, `/docs/api/v2/…`.
SemVer və changelog ilə SDK versiyalarını (npm/maven/pypi) yaradın.
SDK-da köhnəlmiş metodları izahlarla/Deprecated ilə qeyd edin.

11) Versiyalara görə observability

• RPS/gizli/səhv versiyası ('api _ version' etiket).
• End-point istifadə xəritələri: v1-də başqa kim var?
• Alertlər: «> 10% 4xx due to contract mismatch», «köhnə müştərilər> X% T-tarixindən sonra».

12) Caching və versiyası

Yoldakı versiya CDN-nin keşləşdirilməsini yaxşılaşdırır.

• `Vary: Accept, X-API-Version`.
• Cache açarlarını sındırmaq üçün MINOR-da cavab semantikasını dəyişdirməyin.

13) Təhlükəsizlik

JWT versiyasını şifrələməyin və ya əlavə etməyin - versiya token deyil, sorğunu təyin edir.
Daxili montaj nömrələrini açıqlamayın. Xarici mesajlarda «v1/v2» istifadə edin.
MAJOR-da PII-nin validasiyasını, limitlərini, maskalanmasını nəzərdən keçirin.

14) Miqrasiya və avto köməkçiləri

«Migration Guide v1 → v2» dərc edin: sahə uyğunluq cədvəli, sorğu/cavab nümunələri, edge-cases.
Müştərilər üçün köhnəlmiş sahələri işıqlandıracaq linterlər (CLI) təklif edin.
Böyük tərəfdaşlar üçün - iki versiyalı sandbox və test dataseti.

15) Anti-nümunələr

«Əbədi v1»: istifadə müddəti və metrikası yoxdur.
MINOR/PATCH-də gizli pozucu dəyişikliklər.
«Query string versiyası» ('? v = 2') - cache və oxuculuğu pozur.
«Bir end nöqtəsi bayrağın yüz qiymətidir»: sınaqdan keçirmək/sənədləşdirmək çətindir.

16) Giriş çek siyahısı

1. Xarici və daxili müştərilər üçün model (URI/Accept/Header) seçilmişdir.
2. spesifikasiyalar və SDK üçün SemVer, CI avtomatik breaking-check.
3. Deprecation/Sunset siyasət və kommunikasiya şablonları.
4. Gateway-marşrutlaşdırma + kanaryalar, versiyalara görə daşbordlar.
5. Kritik inteqrasiyalar üçün CDC/Contract tests (ödənişlər, KYC, hesabatlar).
6. Sənədlər/SDK/miqrasiya bələdçisi buraxılışla eyni vaxtda dərc edilmişdir.
7. Tarixlər və məsuliyyətli EOL planı.

17) Nümunələr

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

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 Content Negotiation

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

17. 3 GraphQL (sahənin deprikasiyası)

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 Hadisə modeli

• `wallet. v1. balance. updated`
• `wallet. v2. balance. changed '(genişləndirilmiş sxem ilə yeni hadisə)

Sxemlər Registry-də saxlanılır, prodüser uyğunluğu pozan bir sxem ilə hadisələri dərc etmir.

18) iGaming/fintech konteksti (təcrübə)

Ödənişlər: 'status '/' decline _ reason' genişləndirildiyi yeni PSP üçün v2 daxil edin; hesabat üçün mapping v1 → v2 şlyuzunda.
KYC: MINOR 'pep _ screening' sahəsini əlavə edir, müştərilər v1, v2 - tələb edir.
Məsuliyyətli oyunlar/limitlər: MAJOR limit modelini dəyişir (gündəlik/həftəlik). EOL v1 qədər hesabat ikiqat ixrac.
Tənzimləyicilərə hesabat: sabit versiyalar-tarixlər: 'reporting-2025-01'.

19) Mini siyasət (wiki üçün nümunə)

Model: xarici API üçün - 'URI/vN/'; daxili - 'Accept:... vN + json' və ya 'X-API-Version: N'.
SemVer: Spesifikasiyalar və SDK kimi dərc olunur 'N. minor. patch`. MAJOR RFC/ADR tələb edir.
Uyğunluq: MINOR/PATCH - heç bir pozucu dəyişiklik. Qırıcı → yalnız MAJOR vasitəsilə.
Deprecation/EOL: 90 gün ≥ elan; Başlıqlarda Sunset tarixi; kritik müştərilər üçün LTS-filial.
Nəzarət: OpenAPI diff/buf breaking CI, CDC əsas inteqrasiya üçün.
Observability: 'api _ version' etiketli metriklər/loglar.
Relizlər: canary 5% ≥ 24h, sonra mərhələli olaraq 100% yaşıl metrlərlə.

Yekun

Version «/v2 in URL »haqqında deyil, proses haqqında: aydın təkamül qaydaları, avtomatik uyğunluq yoxlamaları, idarə olunan buraxılışlar və inteqrasiyaya hörmət. Aydın siyasət daxil edin, nəzarəti və müşahidəni avtomatlaşdırın - və dəyişikliklər məhsul üçün təhlükə olmağı dayandıracaq.