API жана жаңыртуу шайкештиги
1) Негизги шайкештик принциптери
Additive-first: эски (жаңы кошумча талаалар/endpoints, жаңы enum-баалуулуктар) сындырбай, жаңы кошуу.
Туруктуу контракттар: "спецификацияда эмне убада кылынса, ал иштейт"; жүрүм-туруму документтештирилген.
Backward> Forward: артка шайкештик артыкчылыгы; forward толерант-readers аркылуу жол берилет.
Документтер биринчилик болуп саналат: чындыктын бирден-бир булагы - реестрдеги схеманын версиясы (OpenAPI/AsyncAPI/Proto).
Ачык эволюция: breaking - жаңы негизги версия жана миграциялык гид аркылуу гана.
2) Өзгөрүүлөрдүн таксономиясы
2. 1 шайкеш (MINOR/PATCH)
Кошумча талааларды/хедерлерди, жаңы пункттарды, дефолттор менен query-параметрлерди кошуу.
Лимиттерди көбөйтүү ('page _ size', TTL), коддорду/семантиканы өзгөртпөстөн каталарды тактоо.
Эгерде кардарлар "бейтааныш" (толерант-reader) эске албаса, enum маанилерин кошуу.
2. 2 түшүнүксүз (Behavioral)
Дефолтторду, сорттоо тартибин, жука таймауттарды, квоталарды өзгөртүү - бизнес-логиканы "бузушу" мүмкүн. RFC + жарыялоо жана канарейка талап кылат.
2. 3 сындыруучу (MAJOR)
Талаалардын атын өзгөртүү/алып салуу, түрүн/форматын өзгөртүү, ката коддорун алмаштыруу, контракттардын/аутентификация схемаларынын тескери шайкештиги.
3) чыгаруу саясаты
Стратегия: 'path versioning' ('/v1 ', '/v2').
Minor/патч: "кошуу, сындырып жок".
Date аталыштары (кошумча): 'X-API-Version-Date' жумшак акырындык менен өзгөрүүлөр үчүн.
Медиа түрлөрү : `Accept: application/vnd. acme. v1 + json 'жука грануляция үчүн.
4) Депрекация жана sunset
4. 1 Байланыш аталыштары
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 чыгаруу тартиби
1. порталында жарыялоо/почта/SDK release notes.
2. эскертүү терезе ≥ 90-180 күн.
3. Дашборддогу статустар adoption.
4. Sunset кийин - 410 Gone же "read-only" режими менен макулдашылган болсо, grace мезгил.
5) Миграция жана чогуу жашоо версиялары
өткөөл мезгил ичинде Dual-write/dual-окуу жана отчетторду салыштыруу.
Adapters (убактылуу): эски payload → жаңы схемалар gateway-өзгөртүү; адаптеринин өмүрү чектелген.
SDK-жардам: депрекация эскертүүлөрү менен эки версияны тең колдогон релиздер (процесске 1 жолу).
Фича-желектер: ачкычтар/тенанттар тизмеси боюнча жаңы семантиканы киргизүү.
6) Backward жана Forward шайкештик
6. 1 Backward (эски кардарлар жаңы сервер)
Түрлөрдүн форматтарын/милдеттүүлүгүн өзгөртпөө.
Жаңы талаалар - гана кошумча.
Каталар - мурунку 'error _ code', жаңы коддорду кошуу, алмаштырбоо.
6. 2 Forward (жаңы кардарлар эски Server)
'OPTIONS '/'/versions' аркылуу мүмкүнчүлүктөрдү (capabilities) текшерүү.
Грейс-жүрүм-туруму: кардар жок phichs чыдамкай болушу керек.
7) Келишимдер жана автоматтык текшерүү
Registry: схемалар нускасын сактоо; PR-дифтар → отчеттор "breaking/non-breaking".
Линтер: аттары/түрлөрү, боштук, pagination, туруктуу коддору.
CDC (Consumer-Driven Contracts): CI берүүчүгө интегратор тесттер (Pact жана аналогдор).
Gate: PR 'major bump '/RFC жок breaking учурунда бөгөттөлгөн.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Канар чыгаруу жана артка кадам
Canary: 10% → 25% → 50% → 100% трафик; SLO (5xx/latency/429) начарлашы менен auto-артка.
Бета-ачкычтар: allowlist боюнча жаңы версияларга жетүү.
Release freeze: error-budget күйүп жатканда.
Кабыл алуу аналитикасы: трафиктин/кардарлардын жаңы версиядагы үлүшү, миграция убактысы.
9) майда-чүйдөсүнө чейин шайкештиги: ката, pagination, idempotentity
9. 1 каталар
Иштеп жаткан сценарийлерде HTTP статусун өзгөртүүгө болбойт.
'error _ code' - туруктуу; жаңы коддору гана кошуу.
'application/problem + json' - бирдиктүү формат.
9. 2 Пагинация
эски 'offset/limit' колдоого алынса, cursor/keyset = MINOR өтүү.
Документ сорттоо '(updated_at,id)' жана курсор туруктуулугу.
9. 3 Idempotency
write үчүн - 'Idempotency-Key' + '409 IDEMP_REPLAY' чыр-чатакта.
Миграция демпотенттик семантикасын өзгөртпөшү керек.
10) Gateway-өзгөртүү (туура болгондо)
Map v1 → v2 талаалар, каталарды нормалдаштыруу, дата/акча форматтарын конвертациялоо.
Guardrails: трансформация ачык-айкын жана логикалык; breaking жашыруу эмес, бирок чектелген мөөнөтү менен көпүрө катары колдонушат.
11) Коммуникациялар жана портал
Changelog с датами (`added/changed/deprecated/removed/fixed`).
Version Card: статусу (beta/GA/deprecated), датасы sunset, Гайд шилтемелер.
эскертүүлөр Webhuke: 'deprecation. notice`, `version. released`, `plan. change`.
SDK release notes + баннер порталында.
12) Ийгиликтин метрикасы
Adoption rate v2 (суроо-талап/кардарлар боюнча).
Backward-compat incidents ("сынык" саны).
Error mix (4xx/5xx/429 үлүштөрү) бошотулганга чейин/кийин.
Time-to-Adopt медиа.
Support load (билеттер/жума).
Cost-to-Serve (чакыруу үчүн инфраструктуралык наркы).
13) Үлгүлөр жана мисалдар
13. 1 Версиялар жана депрекациялардын аталыштары
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Версиялар саясаты (YAML фрагменти)
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: шайкеш талаа кошуу
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) релиз чек тизмеси (MINOR/MAJOR)
MINOR
- DIFF: эмес breaking, жашыл Линтер
- Документтер/SDK жаңыртылган (мисалдар/codec)
- Канарейка + SLO боюнча auto-rebound
- Комм-план, порталдагы бет
- Dashbord adoption жана каталар
MAJOR
- RFC/ADR, күн жана терезе ≥ 90-180 күн
- v1 v2 көпүрө (gateway) жана миграциялык жол
- Dual-write/окуу жана текшерүү
- эки API + эскертүү менен SDK
- Негизги интеграторлор менен учкуч
15) Ишке ашыруу планы (3 итерация)
1. пайдубалы (2 жума):
CI схемалар, линт жана auto-diff каттоо; шайкештик саясаты; 'Deprecation/Sunset' аталыштары.
2. Башкарылуучу релиздер (3-4 жума):
Канарейка, фича-желектер, SLO-алерта; версиялар порталы; SDK-релиздер колдоосу менен 2 бутактары.
3. Автоматташтыруу жана масштаб (үзгүлтүксүз):
CDC-CI керектөөчүлөрдүн сыноолору, adoption тенденциялары боюнча sunset болжолу, автоматтык эскертүүлөр жана эскертүүлөр.
16) Mini-FAQ
Мен негизги жок талаа түрүн өзгөртүүгө болобу?
Жок. Жада калса "сап → сан" - breaking. жаңы талааны киргизүү, эски - deprecate.
Enum: маанилерди кошууга болобу?
Ооба, эгерде кардарлар - толерант-readers. Болбосо - биринчи эскертүү жана бета.
эски нускасын сактоо үчүн канча?
жаңы ≥ adoption чейин 95% жана депрекация терезе сакталып турат. Саясатта мөөнөттү белгилеңиз.
Жыйынтык
API шайкештиги - бул дисциплина: additive-мамиле, формалдуу схемалар жана дифтар, канар релиздери, ачык депрекациялар жана башкарылуучу миграция. Өзгөртүү саясатын бекитүү, текшерүүлөрдү жана коммуникацияларды автоматташтыруу, adoption өлчөө - жана сиздин жаңыртууларыңыз кардарларды бузууну токтотот жана эволюциянын ылдамдыгы ишенимдүүлүктү жоготпостон өсөт.