API және жаңарту үйлесімділігі
1) Үйлесімділіктің базалық қағидаттары
Additive-first: ескісін бұзбай, жаңасын қосыңыз (жаңа қосымша өрістер/эндпоинттер, жаңа enum мәндері).
Тұрақты келісімшарттар: «спецификацияда уәде етілгендер жұмыс істейді»; мінез-құлық құжатталған.
Backward> Forward: кері сыйысымдылық артықшылығы; forward tolerant-readers арқылы рұқсат етіледі.
Құжаттар бастапқы: жалғыз шындық көзі - registry (OpenAPI/AsyncAPI/Proto) схемасының нұсқасы.
Айқын эволюция: breaking - тек жаңа major-нұсқасы және көші-қон гиді арқылы.
2) Өзгерістердің таксономиясы
2. 1 үйлесімді (MINOR/PATCH)
Опциондық өрістерді/хедерлерді, жаңа эндпоинттерді, дефолттары бар query-параметрлерді қосу.
Лимиттерді ұлғайту ('page _ size', TTL), кодтарды/семантиканы ауыстырусыз қателерді нақтылау.
Егер клиенттер «бейтаныс» (tolerant-reader) дегенді елемесе, enum мәндерін қосу.
2. 2 Әртүрлі (Behavioral)
Дефолттардың, сұрыптау тәртібінің, жұқа таймауттардың, квоталардың өзгеруі бизнес-логиканы «бұзуы» мүмкін. RFC + анонс пен канареяларды талап етеді.
2. 3 Сынатын (MAJOR)
Өрістерді қайта атау/жою, түрін/пішімін өзгерту, қате кодтарын ауыстыру, келісімшарттардың/аутентификация схемаларының кері үйлеспеушілігі.
3) Нұсқалау саясаты
Стратегия: 'path versioning' ('/v1 ', '/v2').
Минор/патч: «қосу, сындырмау».
Күні көрсетілген тақырыптар (қосымша): '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) Көшi-қон және нұсқалардың бiрлесiп қатар өмiр сүруi
Өтпелі кезеңде dual-write/dual-read және есептермен салыстыру.
Адаптерлер (уақытша): ескі payload → жаңа схемалар; адаптердің өмір сүру мерзімі шектеулі.
SDK-көмек: екі нұсқаны қолдайтын релиздер, депрекация ескертулерімен (процеске 1 рет).
Фича-жалаулар: кілттер/тенанттар тізімі бойынша жаңа семантиканы қосу.
6) Backward және forward үйлесімділігі
6. 1 Backward (ескі клиенттер жаңа сервер)
Түрлер пішімін/міндеттілігін өзгертпеңіз.
Жаңа өрістер - тек опциондық.
Қателер - бұрынғы 'error _ code', жаңа кодтарды қосу, алмастыру.
6. 2 Forward (жаңа клиенттер, ескі сервер)
Мүмкіндіктерді (capabilities) 'OPTIONS '/'/versions' арқылы тексеру.
Грейс-мінез-құлық: клиент жоқ фичтерге төзімді болуы тиіс.
7) Келісімшарттар және автоматты тексерулер
Registry: схемалардың нұсқаларын сақтаймыз; PR-дифтар → «breaking/non-breaking» есептері.
Линтер: аттары/түрлері, ұқсастығы, пагинациясы, тұрақты кодтары.
CDC (Consumer-Driven Contracts): жеткізушінің CI-дегі интегратор тестілері (Pact және аналогтар).
Гейт: 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).
Бета-кілттер: allowlist бойынша жаңа нұсқаларға қатынау.
Release freeze: error-budget жанған кезде.
Қабылдау талдауы: трафиктің/клиенттердің жаңа нұсқадағы үлесі, көші-қон уақыты.
9) Детальдардағы үйлесімділік: қателер, пагинация, іспеттілік
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`).
Нұсқа карточкасы: мәртебесі (beta/GA/deprecated), sunset күні, гайдтарға сілтемелер.
Ескерту веб-хаттары: '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: non-breaking, жасыл линтер
- Құжаттама/SDK жаңартылды (мысалдар/кодектер)
- Канарейка + SLO бойынша авто-кері қайту
- Комм-жоспар, порталдағы бет
- Дашборд adoption және қателер
MAJOR
- RFC/ADR, күн және терезе ≥ 90-180 күн
- v1 v2 көпір (gateway) және көші-қон гид
- Dual-write/read және салыстыру
- SDK екі API + ескерту
- Негізгі интеграторлары бар ұшқыш
15) Енгізу жоспары (3 итерация)
1. Іргетас (2 апта):
CI-дегі схемаларды, линтті және auto-diff тіркеу; үйлесімділік саясаты; 'Deprecation/Sunset' тақырыптары.
2. Басқарылатын релиздер (3-4 апта):
Канарейка, фича-жалаулар, SLO-алерта; нұсқалар порталы; 2 тармақты қолдайтын SDK релиздері.
3. Автоматтандыру және масштаб (үздіксіз):
CI-дегі тұтынушылардың CDC-тестілері, adoption трендтері бойынша sunset болжамы, автоматты нотификациялар мен ескертулер.
16) Шағын FAQ
Өріс түрін majorсыз өзгертуге бола ма?
Жоқ. Тіпті «жол → сан» - breaking. Жаңа өрісті, ескісін - deprecate енгізіңіз.
Enum: мәндерді қосуға бола ма?
Иә, егер клиенттер толерант-readers болса. Әйтпесе - алдымен құлақтандыру және бета.
Ескі нұсқаны қанша сақтау керек?
Әзірге жаңа ≥ adoption 95% және депрекация терезесі сақталған. Саясатта мерзімді белгілеңіз.
Жиынтығы
API үйлесімділігі - бұл пән: additive-тәсіл, формальды схемалар мен дифтар, канареялық релиздер, анық депрекациялар және басқарылатын көші-қон. Өзгерістер саясатын бекітіңіз, тексерулер мен коммуникацияларды автоматтандырыңыз, adoption өлшеңіз - жаңартуларыңыз клиенттерді бұзуды тоқтатады, ал эволюция жылдамдығы сенімділікті жоғалтпай өседі.