API Feedback Loop we wersiýalaryň ewolýusiýasy

1) Näme üçin dolandyrylýan Feedback Loop gerek?

Döwülmek töwekgelçiligini azaltmak: müşderileriň irki signaly we gabat gelmeýän awto-detekt.
Adoption: Çitler çaklamalara däl-de, hakyky ssenariýalara esaslanýar.
Neşirleriň çaklanylyşy: kesgitlenen wersiýa senenamasy we aç-açan deprekasiýa penjireleri.
Ykdysadyýet: "döwülen integrasiýalara" az goldaw, üýtgeşmeleriň bahasy arzan.

2) Seslenme kanallary (we olaryň agramy)

Ulanyş telemetriýasy (endpointler/parametrler/ýalňyşlyklar boýunça) - hakykatyň esasy çeşmesi.
RFC müşderilerden/içerki toparlardan - gurluşly teklipler.
NPS/DevEx we "integrator söhbetdeşlikleri" - hil seslenme.
Issues/forum/portal - meseleler barada çalt signal.
Support/Slack - metrlerde görünmeýän hadysalar.

3) "Feedback Loop" arhitekturasy (maglumat akymlary)

Producers (SDK/şlýuz/portal) → Usage & Error Bus → DWH/Leýk → Awto-dif/lint → Dashboard & Alerts → Roadmap/Backlog.

• Ýygnamak: jaň hasaplaýjylary, parametrler, wersiýa sözbaşylary, ýalňyşlyk kodlary, latency.
• Analitika: adoption trendleri, "öli" meýdanlar, ýygy-ýygydan 4xx/5xx, relizler bilen baglanyşyk.
• Şertnamalara gözegçilik etmek: schema-diff, CDC (consumer-driven contracts), API linter.
• Gowernans: RFC/ADR, Release Council, wersiýalaryň we deprekasiýalaryň senenamasy.

4) Wersiýa syýasaty (SemVer + kanallar)

SDK/müşderiler üçin SemVer: 'MAJOR. MINOR. PATCH`.
API wersiýalary: 'v1', 'v2' (döwüjiler - diňe major). Minor - gabat gelýän meýdanlary/endpointleri goşýarlar.
Üpjünçilik kanallary: 'experimental' → 'beta' → 'GA' → 'deprecated' → 'sunset'.

Wersiýany nirede saklamak

URL ýoly: '/v1/... '- düşnükli we kesilen.
Sözbaşy: 'X-API-Wersiýa: 2025-11-03' - "bellenen" şertnamalar üçin.
Content-Negotiation: `Accept: application/vnd. acme. v1 + json '- inçe granulýasiýa.
Bir esasy usuly saýlaň, galanlary - gabat gelmek/göçmek.

5) Gabat gelmek we "goşmak hukugy"

• Enum (eger müşderiler tolerant-reader bolsa) goşmaça meýdanlary/bahalary goşmak.
• Defolt semantikasy bolan täze endpointler/kweri parametrleri.
• Çäkleri/ölçegleri artdyrmak (şertnamalar saklanylanda).

• Meýdançalaryň adyny üýtgetmek/aýyrmak, görnüşlerini/formatlaryny üýtgetmek.
• Borçlylygyň, ýalňyşlyklaryň/statuslaryň semantikasynyň üýtgemegi.
• Müşderiniň logikasyna täsir edýän defoltlaryň üýtgemegi.

Düzgün: az jady, has düşnükli ("gaýtadan kesgitlenen" meýdanlaryň ýerine täze wersiýalar).

6) RFC/ADR prosesi (jemi)

1. Inisiatiwa (RFC) - höweslendiriş, ulanyş amallary, täsirler, alternatiwalar.
2. Baha bermek (arh-revyu) - howpsuzlyk, gabat gelmek, SLO, finops.
3. ADR - netijeleri bilen kabul edilen karar.
4. Design Freeze - prototip/ROS, şertnama synaglary.
5. Durmuşa geçirmek - Ficha-baýdaklar, canary/beta kanaly, syn edilmegi.
6. GA - resminamalar/SDK/migrasiýa, SLO, goldaw.
7. Deprecation/Sunset - çekiş meýilnamasy, awtosignallar, SLA karzlar ýalňyşlyklarda.

yaml rfc: RFC-0027 title: "Reports v2 cursor pagination"
motivation: "Offset causes drift at high churn"
breaking_change: false rollout: ["beta", "region=eu-west-1", "10% tenants"]
metrics: ["adoption_rate", "error_rate{status=422,429,5xx}", "latency_p95"]
migration: "v1=read-only 90d; dual-write v1/v2 30d"

7) Shemalar we awto-dif (OpenAPI/AsyncAPI/Proto)

Bir çeşme: repozitoriýadaky shemalar (monorepo ýa-da versioned registry).
Awto-dif PR → baýdak "döwýär/döwmeýär"; gabat gelmeýän üýtgeşmeler üçin bloklaýjy gate.
Linter: atlar/görnüşler, durnukly 'error _ code', paginasiýa/idempotentlik barlagy.
CDC: sarp ediji şertnamalary (consumer tests) - CI-e girmek; → "gyzyl düwme".

yaml
- name: API Schema Diff run: api-diff --from main --to PR --fail-on=breaking --report artifact. json

8) Beta, canary, feature flags

Beta: opt-in tenantlar/açarlar, RPS/geo çäklendirmeleri.
Canary:% traffigi ýa-da müşderileriň sanawy boýunça, SLO signallary boýunça awto-yza gaýdyp gelmek (ýalňyşlyklar/gizlinlik/429).
Feature Flags: deploýsyz hereketleri açýar/öçürýär; -hyzmatda saklaň, auditi ýazga alyň.

9) Deprekasiýa we sunset

Bildiriş: changelog + portal, webhuklar "deprecation. notice", sözbaşy' Deprecation: true'.
Penjire: azyndan 90-180 gün (kritiklige bagly).
Maslahatlar: 'Link: <...>; rel="deprecation"` и `Rel: "successor-version"`.
Syn edilişi: daşbord "v1-de başga kim? ", awto-hatlar/portal bellikleri.
Sunset: sözbaşy 'Sunset: 2026-03-31T00: 00: 00Z', möhletden soň - 410 Gone yzyna gaýtarylýar.

json
{
"type": "deprecation. notice",
"api": "reports. v1",
"sunset_at": "2026-03-31T00:00:00Z",
"migrate_to": "reports. v2",
"guides": ["reports-v2-migration"],
"contact": "support@example. com"
}

10) Göçmek we wersiýalaryň bilelikde bolmagy

Göçmek wagty üçin Dual-read/Dual-write; yzygiderliligi hasabatlar bilen deňeşdirmek.
Köne müşderiler üçin adapterler (thin) diňe wagtlaýyn çäre.
Migrasiýa gaýdylary: meýdan kartasy, haýyşlaryň mysallary, ýygy-ýygydan duzaklar.
SDK: iki wersiýany hem-de "deprecation warnings" (her prosesde 1 gezek) goldaýan neşirler.
Synag stendi: sandyk gutusy v2, fiksturlar/maglumat generatorlary.

11) Ewolýusiýanyň üstünlikleriniň metrikleri

Adoption rate v2: Täze wersiýadaky% traffik/müşderiler.
Time-to-Adopt: migrasiýa wagtynyň medianasy.
Backward-compat incidents: "döwükler" sany.
Error mix: goýberilenden soň 4xx/5xx paýy, 422/429 partlama.
DevEx: "Ilkinji üstünlikli haýyşyň" NPS/wagty.
Cost-to-Serve: çagyryş/hasabat üçin infrastruktura bahasy.

12) Üýtgeşmeleri dolandyrmak we alertler

Pre-GA SLO: beta/canary üçin aýratyn bosagalar; çalt we haýal burn düzgünleri.
Alertler: 5xx/latency ýokarlanmagy, täze endpointlerde 422/429 beýikligi, adoption güýji.
Release freeze yananda error-budget.

13) Resminamalar, portal, aragatnaşyklar

Changelog с датами (added/changed/deprecated/removed/fixed).
Gollanmalar: göçmek, mysallar, "täzeleniş barlag sanawy".
Portal: hyzmat boýunça wersiýa kartoçkasy, statuslar, senesi sunset, API-sandbox v2, "elýeterliligi soraň" düwmesi.
Komm paketi: poçta, RSS, portalda bannerler, SDK release notes.

14) Wersiýalaşdyrmak syýasatynyň mysaly (выдержка)

yaml versioning:
strategy: "path"   # path    header    media compatibility:
minor: "additive-only"
patch: "bugfix/perf/no schema change"
deprecation:
min_notice_days: 120 comms: ["portal", "email", "status-webhook"]
rollout:
stages: ["exp", "beta", "ga"]
canary_policy:
step: [10,25,50,100]
checks: ["5xx_rate","p95_latency","429_rate","adoption"]

15) Consumer-Driven Contracts (CDC)

Üpjün ediji shemany we mysallary çap edýär.
Sarp ediji üpjün edijiniň CI-de tassyklanan garaşmalary (pact/hoverfly) saklaýar.
Düzgün: azyndan bir gol çekilen sarp edijini döwýän wersiýany çykaryp bolmaz (eger migrasiýa penjiresi berjaý edilmese we ylalaşylsa).

16) Anti-patternler

Wersiýa/resminamasyz meýdan semantikasynyň "ýuwaş" üýtgemegi.
Minor relizlerde gizlenen breaking-changes.
"Hemişelik" köne wersiýalary üçin tükeniksiz goldaw.
Metrik adoption → köne wersiýany ýapyp bilmeýär.
Şertnamada görkezilmedik SDK-nyň artykmaç jadysy.
Bölünen shemalar (çeşme bir däl).

17) Täze MINOR/MAJOR-yň goýberilişiniň çek-sanawy

• RFC/ADR tassyklandy; Howpsuzlyk/finops/gözegçilik edilýändigi baha berildi.
• Registriýadaky shemalar; ýaşyl linterler; auto-diff breaking (MINOR üçin) görkezmeýär.
• Beta baýdaklar; canary meýilnama; auto-rollback по SLO.
• Resminamalar/SDK/mysallar täzelendi; migrasiýa gollanmasy taýýar.
• Portal: wersiýa kartoçkasy, deprekasiýa/giriş banneri.
• Komm-meýilnama (poçta, status webhuklar) we senesi sunset.
• Daşbordlar adoption/hatalar; alertler açyldy.
• Kanuny/şertnama şertleri (eger SLA/billing üýtgese).

18) Durmuşa geçirmek meýilnamasy (3 iterasiýa)

Yterasiýa 1 - Binýat (2 hepde)

Endpointler we wersiýalar boýunça ulanmak/ýalňyşlyk telemetriýasyny açyň.
Shemalary registriýada başla, CI-de lint we auto-diff sazla.
Wersiýalaryň we deprekasiýalaryň syýasatyny kesgitlemek; portalda çap etmek.

Yterasiýa 2 - Dolandyrylýan goýberişler (3-4 hepde)

RFC/ADR-prosesini, canary/beta ficha-baýdaklar we awto-rollback bilen ornaşdyrmak.
Üpjün edijiniň CI-de esasy sarp edijileriň CDC synaglary.
Daşbordlar adoption/hatalar, komm-şablonlar we webhuklar "deprecation. notice».

Yterasiýa 3 - Masştab we awtomatlaşdyryş (üznüksiz)

Shemalardan SDK/doklaryň awto-emele gelmegi; otly.
Köp wersiýaly sandyk gutusy; göçmek üçin dual-write.
Adoption tendensiýasy boýunça sunset senesini çaklamak; awto-remainderler.

19) Mini-FAQ

Her hili oňaýsyzlyk ýüze çykan halatynda maýory hemişe bumping gerekmi?
Ýok. Eger üýtgeşmeler goşmaça bolsa we bar bolan müşderileri bozmasa - MINOR. MAJOR diňe gabat gelmezlik üçin.

Data wersiýasy ýa-da 'v2'?
'v2' resminamalary we keshleri üçin has aňsat. Bellenen sözbaşylar "ýumşak" gabat gelmezlikler we A/B üçin amatlydyr.

v1 ýapmagyň wagtynyň gelendigine nädip düşünmeli?
Adoption v2> 95%, v1-de möhüm müşderiler ýok, deprekasiýa penjiresi saklanýar, ýalňyşlyklar/goldaw v1 → iň az.

Jemi

Güýçli API öňünden aýdylýar: telemetriýa we CDC töwekgelçilikleri tutýar, RFC/ADR aç-açan çözgütleri berýär, canary/beta ýalňyşlygyň bahasyny peseldýär we anyk wersiýa we deprekasiýa syýasaty üýtgeşmeleri müşderiler üçin howpsuz edýär. Shemalaryň ýeke-täk çeşmesini düzüň, dif/lint we aragatnaşyklary awtomatlaşdyryň, adoption ölçäň - goýberişleriňiz integratorlary "döwmegi" bes eder we önümiň ösüş tizligi ýokarlanar.