API версиясы жана келишимдик шайкештик

TL; DR

Шайкештик - бул ийгилик эмес, тартип. Так версиялар саясатын (SemVer), өзгөрүүлөрдүн математикасын (бул "бузат", бул жок), контракттык тесттерди, схемалардын регистрлерин жана Sunset-процедураларды сактаңыз. Акча жана комплаенс үчүн - vN менен катуу REST/gRPC, UI агрегаттары үчүн - '@deprecated' менен эволюциялык GraphQL. Ар дайым: Канар трафик, тескери шайкештик ≥ бир релиздик цикл, миграциялык гиддер, талааларды пайдалануу телеметриясы.

1) Негизги түшүнүктөр жана максаттар

Backwards-compatible (BC): Жаңы сервер эски кардарларга ылайыктуу.
Forwards-compatible (FC): Эски серверге жаңы кардарлар ылайыктуу (чектелген).
Wire шайкештиги: "зым" боюнча формат сынган эмес (өзгөчө gRPC/Protobuf үчүн маанилүү).
SemVer: `MAJOR. MINOR. PATCH '- келишимди бузуп → MAJOR жогорулатуу.

Максаты: бузуучу өзгөрүүлөрдү азайтуу жана болжолдуу миграция терезелерин камсыз кылуу.

2) Өзгөрүү матрицасы: эмне болот жана эмне болбойт

Өзгөртүү түрү	REST	gRPC (Protobuf)	GraphQL
Талааны кошуу (response)	+ коопсуз	+ коопсуз (жаңы field саны)	+ коопсуз
Кошумча талаа (request)	️ Эгер сервер жок болсо	+ коопсуз	+ коопсуз
Талааны өчүрүү	- сындыруучу	- номерди кайра пайдалансаңыз	️ аркылуу '@deprecated' → терезеден кийин алып салуу
Талаанын атын өзгөртүү	- сындыруучу	- (атын, номерин өзгөртүү)	️ alias/убакыт үчүн эки талаа
Түрүн/форматын өзгөртүү	- сындыруучу	- wire-түрү өзгөргөндө	- схеманы бузса
Статустардын/каталардын семантикасын өзгөртүү	- сындыруучу	- коддору/деталдары - контракт	- кардарларды бузат
Enum тартибин өзгөртүү	️ Мааниси боюнча коопсуз	️ Эгер номерлер туруктуу болсо	+ аты коопсуз
Жаңы endpoint/ыкмалары	+ коопсуз	+ коопсуз	+ коопсуз
Пагинация/чыпкаларды өзгөртүү	️ Кылдат, параметрлерин кошуу	+ жаңы талаалар аркылуу	+ жаңы аргументтер аркылуу

3) API ар кандай стили үчүн саясат

3. 1 REST

URI версиясы ('/v1/... ') же доменде (' api-v1. '). аталышы версия - ички учурларда гана.
Кошуу, жок кылбаңыз: жаңы талаалар - ок, эскилери - схемада "deprecated" деп белгиленип, жок дегенде бир циклге калтырыңыз.
Статустар/каталар: коддорду жана 'error' түзүмүн өзгөртпөө. code/error. message/error. details`.
Демпотенттик өзгөрүүсүз: коопсуз 'POST' s 'Idempotency-Key' ди "жүрүм-турумдук башка" чакырыкка айландырбаңыз.

3. 2 gRPC / Protobuf

Талаа номерлери ыйык: алыскы номерлерди кайра колдонбоңуз, 'reserved' деп белгилеңиз.
Жаңы optional/repit талааларды кошуу гана; "катуу милдеттүү" - валидация аркылуу, '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 башчылары:

'Sunset: ' - чыгаруу өчүрүү датасы
'Deprecation: true' - версиясы эскирип баратат
`Link: ; rel = "deprecation" '- changelog/HYDE көчүрүү

Мисал (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 + "breaking-changes check" PR боюнча.
Consumer-Driven Contracts (CDC): керектөөчүлөрдүн сыноолору (Pact/аналог) - көрүнбөгөн бузулууларга каршы коргоо.
Changelog: machine-readable (мисалы, 'CHANGELOG. md '+ реестрдеги релиздик ноталар).

6) Талаалардын эволюциясы: практикалык эрежелер

ID/ачкычтар: Жаңы '_ v2' талаасы жана өткөөл мезгилсиз форматты (UUID, int) өзгөртпөө.
Убакыт/акча: UTC ISO-8601/epoch жана amount_minor + акча кармап; масштабын өзгөртүүгө болбойт (тыйын/цент).
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 же узун жол: 1-5-25-50-100% жол.
Compatibility window: минималдуу 1-2 аз бошотуу, көп 6-12 ай тышкы API үчүн.
Feature Flags: жаңы талаалар/логиканын бутактары нускасын өзгөртүү жок камтыйт.
Read/Write-бөлүнүү: биринчи жаңы талааны окуп колдоо кошуу, андан кийин аны жаза баштайт.

9) шайкештик сыноо (практика пакети)

Эски версиялардын жоопторуна алтын тесттер.
Diff-тесттер схемалар: CI боюнча breaking тыюу.
V2 (shadow) үчүн staging боюнча өндүрүштүк жолдорду Replay.
Back/Forward Script: эски Server боюнча жаңы кардар жана тескерисинче (FC алгылыктуу жерде).
Вебхуктардын контракттык тесттери: кол тамганы, форматты, убакытты текшерүү.

10) Метрика жана SLO чыгаруу жараяны

акыркы MINOR кардарлардын% (максаты Sunset алдында 80% ≥).
Чыгарылыштагы шайкештик/жеткиликсиздиктин каталары (максаты - 0).
Эскирген чалуулардын үлүшү (Sunset үчүн азайып баратат).
Кардардын миграциялык убактысы (медиана/p95).
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 жана ролдору

Келишимдин ээси (домен owner), API Steward (эрежелер жана линтерлер), Release Manager (Sunset/Communications).
breaking-өзгөрүүлөр үчүн RFC жараяны: бизнес негиздемеси, көчүрүү планы, экспонаттар, даталар.
Бирдиктүү API каталогу: схемалар, версиялар, Sunset календары, байланыш.

14) Анти-үлгүлөрү

"Тынч" сындыруу: статусу/ката/талаа түрү нускасы жок өзгөртүү.
Protobuf-номерлерди кайра пайдалануу - эски кардарлардын репликасын да жок кылат.
GraphQL эч кандай телеметрия талааларды пайдалануу - жок "тийүү".
Глобалдык v2 бардыгы - чекиттик эволюциянын ордуна мегамиграция.
коомдук API үчүн query параметр Version - ачык-айкын жана аялуу схема.
Миграциялык гиддер жана мисалдар жок - өнөктөштөр сүйрөп кетишет, мөөнөттөр бузулат.

15) Check-list жаңы чыгаруу релизи

Жаңыртылган схемасы (OpenAPI/Protobuf/SDL), линтерлер жана breaking-checks өттү.
Интеграциялык жана контракттык тесттер кошулду (CDC).
SDK даяр/Code мисал/көчүрүү жол жана Changelog.
Киргизилген 'Deprecation/Sunset' (эски версия үчүн) + бет "How to migrate".
Canary/Shadow планы, Алерт жана dashboard салыштыруу метрика.
Кайтарым шайкештик макулдашылган мөөнөткө сакталат.
Кайтаруу планы (rollback) жана тобокелдик матрицасы макулдашылган.

Резюме

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

API версиясы жана келишимдик шайкештик

TL; DR

Резюме

Биз менен байланышыңыз

Ыкчам байланыш

Видео жакында жаңыртылат

Азыр биз долбоорлор менен абдан алекпиз