API versiyası və müqavilə uyğunluğu

TL; DR

Uyğunluq bir intizamdır, şans deyil. Dəqiq versiya siyasətini (SemVer), dəyişiklik riyaziyyatını (nə «qırır», nə yoxdur), müqavilə testlərini, sxem qeydlərini və Sunset prosedurlarını saxlayın. Pul və uyğunluq üçün - vN ilə ciddi REST/gRPC, UI aqreqasiyaları üçün - '@deprecated' ilə təkamül GraphQL. Həmişə: kanarya trafiki, əks uyğunluq ≥ bir buraxılış dövrü, miqrasiya qaydaları, sahələrin istifadəsinin telemetri.

1) Əsas anlayışlar və məqsədlər

Backwards-compatible (BC): köhnə müştərilər yeni serverə uyğundur.
Forwards-compatible (FC): köhnə serverə yeni müştərilər uyğun gəlir (məhdud).
Wire-uyğunluq: «tel» formatı qırılmaz (xüsusilə gRPC/Protobuf üçün vacibdir).
SemVer: `MAJOR. MINOR. PATCH '- müqaviləni pozursunuz → MAJOR artırırsınız.

Məqsəd: pozucu dəyişiklikləri minimuma endirmək və proqnozlaşdırıla bilən miqrasiya pəncərələrini təmin etmək.

2) Dəyişiklik matrisi: nə edə bilər, nə edə bilməz

3) Müxtəlif API stilləri üçün siyasət

3. 1 REST

URI-də ('/v1/... ') və ya domendə (' api-v1. ') versiyası. Başlıq versiyası - yalnız daxili hallar üçün.
Əlavə edin, silməyin: yeni sahələr - tamam, köhnə sahələr - sxemdə 'deprecated' kimi qeyd edin və ən azı bir dövrə buraxın.
Status/səhvlər: kodları və strukturunu dəyişdirməyin 'error. code/error. message/error. details`.
İdempotentlik dəyişməz: təhlükəsiz 'POST' s 'Idempotency-Key' -ni «davranış fərqli» çağırışa çevirməyin.

3. 2 gRPC / Protobuf

Sahə nömrələri müqəddəsdir: uzaq nömrələri yenidən istifadə etməyin, 'reserved' kimi qeyd edin.
Yalnız yeni optional əlavə/repit sahələri; «sərt məcburi» - validasiya yolu ilə, 'required'.
Version paketləri: 'payments. v1`, `payments. v2`.
Xidmətlərin uyğunluğu: yeni RPC → yeni üsul; köhnə davranış dəyişməz.

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3. 3 GraphQL

v2 olmadan təkamül: sahələr/növlər əlavə edin; silinir - pəncərə elanı ilə '@deprecated (reason)' vasitəsilə.
Persisted Queries: ictimai müştərilər üçün ağ sorğu siyahısından istifadə edin - uyğunluğu idarə etmək daha asandır.
Field-level authZ və telemetriya: aradan qaldırılmadan əvvəl hansı sahələrdən istifadə olunduğunu bilin.

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3. 4 Vebhuklar

Versiya yolda ('/webhooks/v1/payments ') və hadisənin sabit zərfi (' event _ id ',' type ',' ts ',' data ').
İmzaları/NMAS-ı dəyişməz saxlayın; yeni alqoritmlər - bayraq seçimi kimi.
Uzantılar - yalnız yeni 'data.' və 'headers' sahələri vasitəsilə - köhnələri silmədən.

4) API Gateway və marşrutlaşdırma versiyası

Rules-based routing: prefiks '/v1 ', başlıq' X-Api-Version ', domen.
Shadow/Canary: prodakşn trafikinin bir hissəsini yeni versiyada əks etdirin, cavabları müqayisə edin.
Rate/Quotas per-version: miqrasiya zamanı köhnə müştəriləri qoruyur.

• 'Sunset: ' - Versiyası bağlama tarixi
• 'Deprecation: true' - versiyası köhnəlir
• `Link: ; rel = «deprecation» '- changelog/hyde miqrasiya

nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5) Sxemlərin qeydləri və müqavilələr

OpenAPI / JSON Schema для REST; Protobuf descriptors для gRPC; SDL registry для GraphQL.
CI-yoxlamalar: linters + PR-da «breaking-changes check».
Consumer-Driven Contracts (CDC): İstehlakçı testləri (Pact/analoq) - görünməz sınıqlardan qorunma.
Changelog: machine-readable (məsələn, 'CHANGELOG. md '+ reyestrdə buraxılış notları).

6) Sahələrin təkamülü: praktiki qaydalar

ID/açarları: Yeni '_ v2' sahəsi və keçid dövrü olmadan formatı (UUID, int) dəyişdirməyin.
Vaxt/valyuta: UTC ISO-8601/epoch və amount_minor + valyuta saxlayın; miqyasını dəyişməyin (qəpik/sent).
Enum: qiymətləri əlavə edin - tamam; köhnə mənasını dəyişməyin. REST üçün - ints deyil, string dəyərləri verin.
Pagination: cursor-based daha sabit; kursorun semantikasını dəyişdirməyin.

7) Deprikasiya və «Sunset» proseduru

1. Elanlar (T-90/60): changelog, tərəfdaşlara göndərmə, başlıqlar 'Deprecation/Sunset'.
2. Təkrarlanan dövr: V1 və V2 paralel işləyir; V1 cavab/log xəbərdarlıqları ilə təchiz edilmişdir.
3. Telemetriya istifadə: başqa kim V1 çağırır? nöqtə kontaktları.
4. Dondurma V1: yalnız buffs/fich olmadan.
5. Off (Sunset): 410 Gone və ya keçid təlimatları ilə blok səhifə.

8) Ağrısız buraxılışlar: hesablama strategiyaları

Blue/Green və ya Weighted routing: 1-5-25-50-100% trafik.
Compatibility window: xarici API üçün ən azı 1-2 kiçik buraxılış, daha çox 6-12 ay.
Feature Flags: dəyişən versiyası olmadan yeni məntiq sahələri/filialları daxil etmək.
Read/Write-parçalanma: əvvəlcə yeni sahəni oxumaq üçün dəstək əlavə edin, sonra yazmağa başlayın.

9) Uyğunluq testi (təcrübə paketi)

Köhnə versiyaların cavabları üçün Golden testləri.
Diff-test sxemləri: CI-də breaking qadağan.
V2 (shadow) üçün staging istehsal trass Replay.
Back/Forward Script: köhnə serverdə yeni müştəri və əksinə (FC qəbul olduğu yerdə).
Müqavilə vebhuk testləri: imza, format, vaxt yoxlaması.

10) Metrik və SLO versiyası prosesi

Son MINOR-da müştərilərin% -i (hədəf Sunset qarşısında 80% ≥).
Buraxılışda uyğunluq/əlçatmazlıq səhvləri (məqsəd 0).
Köhnəlmiş zənglərin nisbəti (Sunset-ə azalır).
Müştəri miqrasiya vaxtı (median/p95).
Latency/regression delta versiyaları arasında (əsas daha pis deyil).

11) Artefaktların nümunələri

yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }

proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }

graphql type Query { payout(id: ID!): Payout }

12) Əlaqəli kanalların versiyası

SDK/CLI: SemVer + API versiyasından asılılıq, uyğunluq README-də razılaşdırılmışdır.
Hadisələr/axınlar (WS/Kafka): in 'envelope versiyası. version`; yeni atributlar - isteğe bağlıdır; dedup və rezyum versiyaları arasında eyni şəkildə işləyir.
Hesabat/CSV: fayl/papaq adı versiyası; sağdakı sütunları əlavə edin; sıra/növləri dəyişməyin.

13) Governance və rolları

Müqavilə sahibi (domain owner), API Steward (qaydalar və linterlər), Release Manager (Sunset/communications).
Breaking-dəyişikliklər üçün RFC prosesi: biznes əsaslandırma, miqrasiya planı, artefaktlar, tarixlər.
API-nin vahid kataloqu: sxemlər, versiyalar, Sunset təqvimi, əlaqə.

14) Anti-nümunələr

«Sakit» qırılma: status/səhv/heç bir versiyası sahə növü dəyişdirmək.
Protobuf nömrələrinin yenidən istifadəsi - köhnə müştərilərin replikalarını məhv edir.
Telemetriya olmayan GraphQL - «toxunma» aradan qaldırılması.
Qlobal v2 - nöqtəli təkamül əvəzinə meqamiqrasiya.
Ictimai API üçün query parametrli versiya qeyri-aşkar və həssas sxemdir.
Heç bir miqrasiya bələdçisi və nümunəsi yoxdur - tərəfdaşlar sürüşür, şərtlər pozulur.

15) Check-list buraxılış yeni versiyası

• Yenilənmiş sxem (OpenAPI/Protobuf/SDL), keçdi linters və breaking-checks.
• Əlavə inteqrasiya və müqavilə testləri (CDC).
• Hazır SDK/kod nümunəsi/miqrasiya bələdçi və Changelog.
• «Deprecation/Sunset» (köhnə versiya üçün) + «How to migrate» səhifəsi daxil edilmişdir.
• Canary/Shadow plan, alert və dashboard müqayisə metrik.
• Əks uyğunluq razılaşdırılmış müddətə saxlanılır.
• Geri dönüş planı (rollback) və risk matrisi razılaşdırılır.

Xülasə

Sabit API «birdəfəlik» deyil, prosesdir. Qaydalara uyğun yaşayın: SemVer + add-only təkamül + sxemlərin siyahısı + müqavilə testləri + Sunset prosedurları. Stilləri (REST/gRPC/GraphQL) və onların siyasətlərini ayırın, API Gateway versiyalarını marşrutlaşdırın, kanaryalarla yuvarlayın, effekti ölçün. Beləliklə, «sındırıcı sürprizlərdən» qaçacaqsınız, tərəfdaşların inteqrasiyasını sürətləndirəcəksiniz və pul və komplayens kritik domenlər üçün proqnozlaşdırıla bilən olacaqsınız.