API нұсқалау және келісімшарттық үйлесімділік

TL; DR

Үйлесімділік - бұл сәттілік емес, тәртіп. Нақты нұсқалар саясатын (SemVer), өзгерістер математикасын (не «бұзады», не жоқ), келісім-шарт тесттерін, схемалар тіркелімдерін және Sunset-процедураларын ұстаңыз. Ақша мен комплаенс үшін - vN бар қатаң REST/gRPC, UI-агрегациялар үшін - эволюциялық GraphQL с '@deprecated'. Әрқашан: канареялық трафик, кері үйлесімділік ≥ бір релиздік цикл, көші-қон гидтері, өрістерді пайдалану телеметриясы.

1) Базалық ұғымдар мен мақсаттар

Backwards-compatible (BC): жаңа серверге ескі клиенттер келеді.
Forwards-compatible (FC): ескі серверге жаңа клиенттер келеді (шектеулі).
Wire-үйлесімділік: «сым» форматы бұзылмайды (gRPC/Protobuf үшін ерекше маңызды).
SemVer: `MAJOR. MINOR. PATCH '- келісімшартты бұзасыз → MAJOR арттырасыз.

Мақсаты: бұзылатын өзгерістерді барынша азайту және көші-қонның болжамды терезелерін қамтамасыз ету.

2) Өзгерістер матрицасы: не болады, не болмайды

Өзгерту түрі	REST	gRPC (Protobuf)	GraphQL
Өрісті қосу (response)	+ қауіпсіз	+ қауіпсіз (жаңа field number)	+ қауіпсіз
Қосымша өріс қосу (request)	️ егер сервер жоқ болса	+ қауіпсіз	+ қауіпсіз
Өрісті жою	- сындыратын	- егер нөмірді қайта пайдалансаңыз	️ арқылы '@deprecated' → терезеден кейін жою
Өрісті қайта атау	- сындыратын	- (атын, нөмірін өзгертіңіз)	️ alias/уақыт үшін екі өріс
Түрін/пішімін өзгерту	- сындыратын	- wire-типті ауыстыру кезінде	- егер схеманы бұзса
Мәндер/қателер семантикасын өзгерту	- сындыратын	- кодтар/бөлшектер - келісімшарт	- клиенттерді сындырады
Enum ішінде ретін өзгерту	️ мағынасы бойынша қауіпсіз	️ Егер enum нөмірлері тұрақты болса	+ атауы бойынша қауіпсіз
Жаңа endpoint/әдістер	+ қауіпсіз	+ қауіпсіз	+ қауіпсіз
Пагинацияны/сүзгілерді өзгерту	️ ұқыпты, параметрлерді қосу	+ жаңа өрістер арқылы	+ жаңа дәлелдер арқылы

3) Әртүрлі API стильдеріне арналған саясат

3. 1 REST

URI ('/v1/... ') немесе домендегі (' api-v1. ') нұсқасы. Тақырыптық нұсқа - тек ішкі жағдайлар үшін.
Қосыңыз, жоймаңыз: жаңа өрістерді - шамамен, ескілерін - схемада «deprecated» деп белгілеңіз және кем дегенде бір циклге қалдырыңыз.
Мәртебелер/қателер: 'error' кодтары мен құрылымын өзгертпеңіз. code/error. message/error. details`.
Сәйкестік өзгермейді: қауіпсіз 'POST' c 'Idempotency-Key' дегенді «мінез-құлық тұрғысынан басқа» шақыруға айналдырмаңыз.

3. 2 gRPC / Protobuf

Өріс нөмірлері - қасиетті: қашықтағы нөмірлерді қайта пайдаланбаңыз, 'reserved' деп белгілеңіз.
Тек жаңа optional/репит өрістерін қосу; «қатаң міндетті» - валидация арқылы, 'required' емес.
Нұсқалық бумалар: 'payments. v1`, `payments. v2`.
Сервистердің үйлесімділігі: жаңа RPC → жаңа әдіс; ескілердің мінез-құлқын өзгертпейміз.

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-сіз эволюция: өрістерді/түрлерді қосыңыз; жою - терезе аңдатпасы бар '@deprecated (reason)' арқылы.
Persisted Queries: ашық клиенттер үшін ақ сұраулар тізімін пайдаланыңыз - үйлесімділікті бақылау оңай.
Field-level authZ және телеметрия: жою алдында нақты қандай өрістер пайдаланылатынын біліңіз.

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

3. 4 Вебхактар

Жолдағы нұсқасы ('/webhooks/v1/payments ') және оқиғаның бекітілген конверті (' event _ id ',' type ',' ts ',' data ').
Қолтаңбаларды/НМАС-ты өзгеріссіз сақтаңыз; жаңа алгоритмдер - жалауы бар опция ретінде.
Кеңейтімдер тек жаңа 'data.' және 'headers' өрістері арқылы - ескілерін жоймай.

4) API Gateway және нұсқаларын бағыттау

Rules-based routing: префикс бойынша '/v1 ', тақырып бойынша' X-Api-Version ', домен бойынша.
Shadow/Canary: «көлеңкеге» жаңа нұсқасына шығарылған трафиктің бір бөлігін көрсетіңіз, жауаптарды салыстырыңыз.
Rate/Quotas per-version: көшу кезінде ескі клиенттерді қорғайды.

REST үшін Sunset headers:

'Sunset: ' - нұсқасын өшіру күні
'Deprecation: true' - нұсқасы ескіреді
`Link: ; rel = «deprecation» '- changelog/гайд көші-қон

Мысалы (Nginx-style, оңайлатылған):

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) Схемалар тіркелімдері мен келісімшарттар

OpenAPI / JSON Schema для REST; Protobuf descriptors для gRPC; SDL registry для GraphQL.
CI-тексерулер: linters + PR кезінде «breaking-changes check».
Consumer-Driven Contracts (CDC): тұтынушылар тестілері (Pact/аналог) - байқалмайтын сынулардан қорғау.
Changelog: machine-readable (мысалы, 'CHANGELOG. md '+ тізілімдегі релиз-ноталар).

6) Өрістердің эволюциясы: практикалық ережелер

ID/кілттер: Жаңа 'v2' өрісі мен өтпелі кезеңсіз (UUID int) пішімін өзгертпеңіз.
Уақыт/валюта: UTC ISO-8601/epoch және amount_minor + currency; масштабын (тиын/цент) өзгертпеңіз.
Enum: мәндерін қосыңыз - ок; ескілердің мағынасын өзгертпеңіз. REST үшін - ints емес, string-мәндерін беріңіз.
Pagination: cursor-based тұрақтырақ; меңзердің семантикасын өзгертпеңіз.

7) Деприкация және «Sunset» - процедура

1. Анонс (T-90/60): changelog, серіктестерге тарату, «Deprecation/Sunset» тақырыптары.
2. Қайталанатын кезең: V1 және V2 қатар жұмыс істейді; V1 жауаптардағы/логтардағы ескертулермен жабдықталған.
3. Телеметрия пайдалану: тағы кім V1 шақырады? нүктелік контактілер.
4. V1 мұздату: тек багфикстер/фич жоқ.
5. Өшіру (Sunset): 410 Gone немесе көші-қон нұсқаулығы бар блок-бет.

8) Ауыртпалықсыз релиздер: орналастыру стратегиясы

Blue/Green немесе Weighted routing: 1-5-25-50-100% трафик.
Compatibility window: сыртқы API үшін кемінде 1-2 шағын релиздер, 6-12 айдан жиі.
Feature Flags: жаңа өрістерді/логика тармақтарын нұсқасын ауыстырусыз қосу үшін.
Read/Write-бөлшектеу: алдымен жаңа өрісті оқу үшін қолдау қосыңыз, содан кейін оны жазуды бастаңыз.

9) Үйлесімділікті тестілеу (практикалар пакеті)

Ескі нұсқалардың жауаптарына арналған Golden-тестілер.
Схемалардың diff-тесттері: CI-де breaking тыйым салу.
V2 (shadow) үшін staging бойынша Replay продакшн-трассасы.
Back/Forward сценарийлері: ескі серверде жаңа клиент және керісінше (FC рұқсат етілген жерде).
Вебхуктардың келісімшарттық тестілері: қолтаңбаны, пішімді, уақытты тексеру.

10) Метрика және SLO нұсқалау процесі

Соңғы MINOR-дағы клиенттердің% -ы (мақсат Sunset алдында 80% ≥).
Шығарылымдағы сыйысымдылық/қол жетімсіздік қателері (мақсат - 0).
Ескірген нұсқа шақыруларының үлесі (Sunset-ке кему).
Клиенттің көшу уақыты (медиана/п95).
Latency/regression delta нұсқалары арасында (базалықтан кем емес).

11) Артефактілердің үлгілері

OpenAPI (үзік, өріс деприкациясы):

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 }

Protobuf (reserved және v2 пакет):

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

GraphQL (деприкация):

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

12) Аралас арналарды нұсқалау

SDK/CLI: SemVer + API-нұсқасына тәуелділік, сыйысымдылық README-де айтылған.
Оқиғалар/ағындар (WS/Kafka): in 'envelope нұсқасы. version`; жаңа атрибуттар - опциондық; дедуп пен резюм нұсқалар арасында бірдей жұмыс істейді.
Есеп/CSV: файл/бас атауындағы нұсқа; оң жақтағы бағандарды қосыңыз; ретін/түрлерін өзгертпеңіз.

13) Governance және рөлдері

Келісімшарт иесі (domain owner), API Steward (ережелер мен линтерлер), Release Manager (Sunset/коммуникациялар).
Breaking-өзгерістерге арналған RFC процесі: бизнес негіздемесі, көші-қон жоспары, артефакттар, күндер.
Бірыңғай API каталогы: схемалар, нұсқалар, Sunset күнтізбесі, контакт көрінетін жерде.

14) Қарсы үлгілер

«Тыныш» бұзылулар: күйін/қатесін/өріс түрін нұсқасыз өзгертеміз.
Protobuf-нөмірлерді қайта пайдалану - ескі клиенттерді бұзады.
Өрістерді телеметриясыз GraphQL - «қолмен» жою.
Жаһандық v2 барлығы - нүктелік эволюцияның орнына мегамиграция.
Көпшілік API үшін query параметріндегі нұсқа - айқын емес және осал схема.
Көші-қон гайдтары мен мысалдары жоқ - серіктестер сүйретеді, мерзімдері бұзылады.

15) Check-list жаңа нұсқасын шығару

Схема жаңартылды (OpenAPI/Protobuf/SDL), линтерлер мен breaking-checks өтті.
Интеграциялық және келісімшарттық тестілер (CDC) қосылды.
Дайын SDK/кодтың үлгісі/көші-қон нұсқасы және Changelog.
«Deprecation/Sunset» қосылған (ескі нұсқасы үшін) + «How to migrate» беті.
Canary/Shadow жоспары, алерта және дашборд салыстыру метриктер.
Кері үйлесімділік келісілген мерзімге сақталды.
Кері қайтару жоспары (rollback) және тәуекелдер матрицасы келісілді.

Түйіндеме

Тұрақты API - бұл «біржола» емес, процесс. Ережелер бойынша өмір сүріңіз: SemVer + add-only эволюция + схемалар тіркелімі + келісімшарттық тестілер + Sunset-процедуралар. Стильдерді (REST/gRPC/GraphQL) және олардың саясаттарын бөліңіз, API Gateway нұсқаларын бағыттаңыз, канарейкалармен жылжытыңыз, әсерін өлшеңіз. Осылайша сіз «сындыратын тосын сый-сияқтылардан» құтылып, серіктестердің интеграциясын жеделдетіп, ақша және комплаенс-критикалық домендер үшін болжамдылықты сақтайсыз.

API нұсқалау және келісімшарттық үйлесімділік

TL; DR

Түйіндеме

Бізбен байланысыңыз

Жылдам байланыс

Бейне жақында жаңартылады

Қазір біз жобалармен өте қатты айналысып жатырмыз