API we täzelenme laýyklygy
1) Laýyklygyň esasy ýörelgeleri
Additive-first: Köne (täze opsiýa meýdanlary/endpointleri, täze enum-gymmatlyklary) döwmezden täzesini goşuň.
Durnukly şertnamalar: "aýratynlykda wada berlen zat işleýär"; özüni alyp barşy dokumentleşdirildi.
Backward> Forward: tersine gabat gelmek üçin ileri tutulýan ugur; forward tolerant-readers arkaly rugsat berilýär.
Resminamalar başlangyç: Hakykatyň ýeke-täk çeşmesi - registriýadaky shemanyň wersiýasy (OpenAPI/AsyncAPI/Proto).
Aç-açan ewolýusiýa: breaking - diňe täze major wersiýasy we migrasiýa gollanmasy arkaly.
2) Üýtgeşmeleriň taksonomiýasy
2. 1 Gabat gelýär (MINOR/PATCH)
Goşmaça meýdanlary/giderleri, täze endpointleri, defoltly query-parametrleri goşmak.
Çäkleri köpeltmek ('page _ size', TTL), kodlary/semantikany üýtgetmezden ýalňyşlyklary anyklamak.
Müşderiler "nätanyş" (tolerant-reader) manylaryny äsgermezlik etseler, enum bahalaryny goşmak.
2. 2 Düşnüksiz (Behavioral)
Defoltlaryň, sortlamagyň tertibiniň, inçe wagtlaryň, kwotalaryň üýtgemegi - işewürlik logikasyny "bozup" biler. RFC + bildiriş we kanareýa talap edýär.
2. 3 Döwüjiler (MAJOR)
Meýdanlaryň adyny üýtgetmek/aýyrmak, görnüşini/formatyny üýtgetmek, ýalňyşlyk kodlaryny çalyşmak, kontraktlaryň/autentifikasiýa shemalarynyň ters gabat gelmezligi.
3) Wersiýalaşdyrmak syýasaty
Strategiýa: 'path versioning' ('/v1 ', '/v2').
Minor/patch: "goşuň, döwmäň".
Bellenen sözbaşylar (goşmaça): 'X-API-Version-Date' ýuwaş-ýuwaşdan üýtgeşmeler üçin.
Media görnüşleri (ops.) : `Accept: application/vnd. acme. v1 + json 'inçe granulýasiýa üçin.
4) Deprekasiýa we sunset
4. 1 Aragatnaşyk sözbaşylary
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 Çykarmagyň tertibi
1. Portalda/poçta sanawynda bildiriş/SDK release notes.
2. Duýduryş penjiresi ≥ 90-180 gün.
3. Dashborddaky statuslar adoption.
4. Sunset - 410 Gone ýa-da "read-only" düzgüninden soň, eger ylalaşylan bolsa, grace döwri üçin.
5) Wersiýalaryň göçmegi we bilelikde ýaşamagy
Geçiş döwründe dual-write/dual-okamak we hasabatlary barlamak.
Adapterler (wagtlaýyn): köne payload → täze shemalar gateway-öwrümleri; adapteriň ömri çäklidir.
SDK-kömek: iki wersiýany hem goldaýan çykarmalar, deprekasiýa duýduryşlary bilen (her proses üçin 1 gezek).
Ficha-baýdaklar: açarlaryň/tenantlaryň sanawy boýunça täze semantikany goşmak.
6) Backward we forward gabat gelmek
6. 1 Backward (köne müşderiler täze serwer)
Görnüşleriň/borçlylygyň formatlaryny üýtgetmäň.
Täze meýdanlar diňe goşmaça.
Hatalar - öňki 'error _ code', täze kodlary goşmak, çalyşmak.
6. 2 Forward (täze müşderiler köne serwer)
'OPTIONS '/'/versions' arkaly (capabilities) mümkinçiliklerini barlamak.
Greýs-özüni alyp barşy: Müşderi ýok bolan aýratynlyklara çydamly bolmalydyr.
7) Şertnamalar we awtomatiki barlaglar
Registry: shemalaryň wersiýalaryny saklaýarys; PR-difler → "breaking/non-breaking" hasabatlary.
Linter: atlar/görnüşler, idempotentlik, paginasiýa, durnukly kodlar.
CDC (Consumer-Driven Contracts): CI üpjün edijisine integrator synaglary (Pact we analoglar).
Gate: PR 'major bump '/RFC-siz döwülende petiklenýär.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Kanareýanyň goýberilmegi we yzyna gaýdyp gelmek
Canary: 10% → 25% → 50% → 100% traffik; SLO ýaramazlaşanda awto-yza gaýdyp gelmek (5xx/latency/429).
Beta açarlary: allowlist boýunça täze wersiýalara girmek.
Release freeze: error-budget ýakylanda.
Kabul etmegiň seljermesi: traffigiň/müşderileriň täze wersiýadaky paýy, migrasiýa wagty.
9) Jikme-jikliklerde gabat gelmek: ýalňyşlyklar, paginasiýa, idempotentlik
9. 1 Ýalňyşlyklar
Bar bolan skriptlerde HTTP statuslaryny üýtgetmäň.
'error _ code' - durnukly; Diňe täze kodlary goşuň.
'application/problem + json' - ýeke-täk format.
9. 2 Paginasiýa
Köne 'offset/limit' bar bolsa, cursor/keyset = MINOR geçiň.
"(updated_at,id)" sortuny we kursoryň durnuklylygyny resminamalaşdyryň.
9. 3 Idempotency
Write üçin - 'Idempotency-Key' + '409 IDEMP_REPLAY' gapma-garşylykda.
Migrasiýa dempotentligiň semantikasyny üýtgetmeli däldir.
10) Gateway-transformasiýa (ýerlikli bolanda)
Map v1 → v2 meýdanlary, ýalňyşlyklary kadalaşdyrmak, seneler/pul formatlaryny öwürmek.
Guardrails: üýtgeşmeler aç-açan we logistik; breaking däl-de, çäklendirilen köpri hökmünde ulanyň.
11) Aragatnaşyk we portal
Changelog с датами (`added/changed/deprecated/removed/fixed`).
Wersiýa kartoçkasy: status (beta/GA/deprecated), senesi sunset, gidlere salgylanmalar.
Bildiriş webhuklary: 'deprecation. notice`, `version. released`, `plan. change`.
SDK release notes + portalda banner.
12) Üstünligiň metrikleri
Adoption rate v2 (/müşderiler üçin).
Backward-compat incidents.
Error mix (paýlar 4xx/5xx/429) çykarylmazdan öň/soň.
Time-to-Adopt mediana.
Support load (bilet/hepde).
Cost-to-Serve (çagyryş üçin infrastruktura bahasy).
13) Şablonlar we mysallar
13. 1 Wersiýalaryň we deprekasiýalaryň sözbaşylary
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Wersiýa syýasaty (YAML bölegi)
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: gabat gelýän meýdan goşmak
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) Goýbermegiň çek-sanawy (MINOR/MAJOR)
MINOR
- DIFF: breaking däl, ýaşyl linter
- Resminamalar/SDK täzelendi (mysallar/kodekler)
- Kanareýa + SLO boýunça awto-yza gaýdyp gelmek
- Komm-plan, portaldaky sahypa
- Adoption we ýalňyşlyklar
MAJOR
- RFC/ADR, gün we penjire ≥ 90-180 gün
- v1 v2 köpri (gateway) we migrasiýa gollanmasy
- Dual-write/read and contractions
- Iki API + duýduryş bilen SDK
- Esasy integratorly pilot
15) Durmuşa geçirmek meýilnamasy (3 iterasiýa)
1. Binýady (2 hepde):
CI-de shemalary, lintleri we auto-diff hasaba almak; gabat gelmek syýasaty; 'Deprecation/Sunset' sözbaşylary.
2. Dolandyrylýan goýberişler (3-4 hepde):
Kanareýkalar, baýdaklar, SLO-alertler; wersiýalaryň portaly; 2 şahany goldaýan SDK neşirleri.
3. Awtomatlaşdyryş we masştab (üznüksiz):
CI-de sarp edijileriň CDC synaglary, adoption tendensiýalary boýunça sunset çaklamasy, awtomatiki bellikler we ýatlatmalar.
16) Mini-FAQ
Meýdanyň görnüşini major bolmasa üýtgedip bolarmy?
Ýok. Hatda "hat → san" - breaking. Täze meýdany giriň, köne - deprecate.
Enum: manylary goşmak mümkinmi?
Hawa, eger müşderiler tolerant-readers bolsa. Otherwiseogsam, ilki duýduryş we beta.
Köne wersiýany näçe wagt saklamak?
Şu wagta çenli täze adoption 95% ≥ we deprekasiýa penjiresi saklandy. Syýasatda möhleti belläň.
Jemi
API laýyklygy - bu düzgün-nyzam: additive-çemeleşme, resmi shemalar we diflar, kanar relizleri, aç-açan deprekasiýa we dolandyrylýan migrasiýa. Üýtgeşmeler syýasatyny düzüň, barlaglary we aragatnaşyklary awtomatlaşdyryň, adoption ölçäň - täzelenmeleriňiz müşderileri bozmagy bes eder we ewolýusiýa tizligi ygtybarlylygy ýitirmezden öser.