API нұсқалау стратегиялары

Не үшін нұсқалау керек

API клиенттерге қарағанда тез өзгереді. Нұсқалау фич шығаруға және интеграцияның бұзылуынсыз қателерді түзетуге мүмкіндік береді, өзгерістер рәсімін белгілейді және эволюцияны болжауға болады. Кілт: әдепкі аддитивті өзгерістер, majors - тек сыну үшін, автоматты сәйкестікті тексеру және ойластырылған sunset саясаты.

Негізгі қағидаттар

1. Additive-first: жаңа опциондық өрістер/әдістер/оқиғалар - шамамен; мағынасын алып тастау және өзгерту - мажор.
2. MGC (ең төменгі кепілдік келісімшарт) тұрақты; байыту - capabilities/'? include = 'арқылы.
3. Толерант reader: клиенттер белгісіз өрістерді елемейді және enum кеңейтулерін дұрыс бастан кешіреді.
4. Semantic Versioning: `MAJOR. MINOR. Артефакттар, SDK және оқиғалар үшін PATCH '.
5. Automate: schema-diff, линтерлер және CDC тестілері breaking-өзгерістерді бұғаттайды.

Нұсқаны қайда сақтау керек (мекенжай механикасы)

REST/HTTP

URI-нұсқа: '/v1/orders '→ жай бағыттау, шлюздерде ыңғайлы. Минус - идеялар эволюциясын «бөгейді».
Медиатип/тақырып: 'Accept: application/vnd. example. orders. v1 + json '- пішімді дәл басқару; дебаж жасау қиынырақ.
Query-нұсқасы: '? api-version = 1' - A/B үшін ыңғайлы, бірақ кэш/логтарда жоғалту оңай.
Ұсыным: major-желілер үшін URI + feature/capability flags және минорлы кеңейтулер үшін контент-негация.

gRPC / Protobuf

Пакеттер/сервистер: 'package payments. v1; service PaymentsV1; '- анық сызықтар.
Тегтердің нөмірленуі өзгермейді; жойылған тегтерді қайта пайдалануға болмайды.
Жаңа өрістер - 'optional'; breaking → жаңа '.v2'.

GraphQL

URL-де айқын major жоқ сұлба. Көші-қон @deprecated мен терезелері арқылы эволюция; «нағыз» major - жаңа эндпоинт-схема.
complexity/depth бағдарламасын бақылаңыз - бұл келісімшарттың бір бөлігі.

Event-driven (Kafka/NATS/Pulsar)

Оқиға атауы: 'payment. authorized. v1 '- түріндегі нұсқа.
Үйлесімділік режимдері бар схемалар тізілімі (Euro/JSON Schema/Protobuf) (BACKWARD/FORWARD/FULL).
Major → dual-emit 'v1' және 'v2' өтпелі кезеңге.

Нұсқалар моделі және өзгерістер саясаты

Semantic Versioning

MAJOR - бұзатын өзгерістер: өрістерді жою/қайта атау, партиялану кілттерін ауыстыру, мәртебелердің басқа мағынасы, валидацияны қатаңдату.
MINOR - аддитивті: жаңа міндетті емес өрістер/эндпоинттер/оқиғалар, tolerant-reader кезінде жаңа enum-мәндер.
PATCH - келісімшартты және семантиканы өзгертпей түзетулер.

Deprecation & Sunset

Ескірген ('Deprecated: true', '@deprecated') белгісін қойыңыз, sunset-күнін, баламасын және көші-қон нұсқасын жариялаңыз.
HTTP-де - «Sunset», «Deprecation» тақырыптары; оқиғаларда - жеке '.deprecation. notice`.
Алу туралы шешім қабылдау үшін usage телеметриясын жүргізіңіз.

Стиль бойынша нұсқалық стратегиялар

REST

/ v1 ,/v2.
MINOR: схемаларды кеңейту, '? fields =', '? include ='; қауіпсіз enum-кеңейтулер.
ETag/If-Match және сынусыз үйлесімділікке арналған іспеттес POST.
Қателер - тұрақты пішім ('type', 'code', 'trace _ id').

gRPC

'PaymentsV2. Capture`.
Қателер мәртебесі және deadline семантикасы - келісімшарттың бір бөлігі; өзгерту → жаңа әдіс/қызмет.
Стриминг: Хабарлардың реті туралы келісіңіз және оны minor дегенге өзгертпеңіз.

GraphQL

Өрістер мен түрлерді еркін қосыңыз; жою - '@deprecated' + көші-қон терезесі арқылы; үлкен дизайн → жаңа схема ('/graphql-v2 ').
Интроспекция және сипаттамалар - клиенттердің көші-қоны үшін must-have.

Events

Core vs enriched: ядро тұрақты, байыту қатар өмір сүреді және бөлек нұсқаланады.
Партиялану кілті major-сызық шегінде өзгермейді.
Major-көші-қон - 'dual-emit' + проекциялардың/консьюмерлердің көші-қоны.

Negotiation және capability-жалаулар

Capabilities: клиент жібереді 'X-Capabilities: risk_score,price_v2'; сервер кеңейтілген көрініспен жауап береді.
Ішінара жауаптар үшін Prefer (HTTP) және «hints».
Сокеттерде/ағымдарда - қолдау көрсетілетін кеңейтімдер тізімі бар handshake хабарламасы.

Major-нұсқаларын ауырсынусыз шығару

1. RFC/ADR: неге major қажет, не сынады, тәуекелдер матрицасы.
2. Dual-run: 'v1' және 'v2' параллельді іске қосу (оқиғаларды екі рет жариялау, екі gateway-роут, трафикті көрсету).
3. Көші-қон адаптерлері: ауыр клиенттерге арналған прокси/трансляторлар 'v1 v2'.
4. Канарейка: gateway-дегі клиенттер топтары/топиктер/тегтер бойынша.
5. Sunset-жоспар: күндер, коммуникация, стендтер, тест деректері, пайдалану мониторингі.

Платформа мен инфрақұрылымның рөлдері

API Gateway/Service Mesh: нұсқасы, тақырыптары, жолдары бойынша бағыттау; rate-limit и auth per-version.
Schema Registry & Catalog: diff тарихы бар арнайы/схемалар үшін ақиқат көзі.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observability: нұсқа логиге/трейске/метрикаға түсуі керек.

Нұсқаларды тестілеу

Schema-diff в PR: breaking бұғаттау.
Consumer-Driven Contracts: провайдер нақты тұтынушылардың келісімшарттарына қарсы тексеріледі.
Golden samples: нұсқасына эталондық жауаптар.
E2E-канарейка: p95/p99, нұсқалар арасындағы қателер мен таймауттарды салыстыру.
Оқиғалар үшін replay: проекциялар айырмашылықтарсыз v2-ге қайта жинақталады.

Деректер мен дерекқорларды көшіру

REST/gRPC үшін: БД көші-қоны expand-and-contract арқылы үйлестіріледі (бағанды қосыңыз → жаза бастаңыз → оқуға ауысыңыз → ескісін жойыңыз).
Events үшін: dual-emit және консьюмерлер көші-қоны; кейде - логтың жаңа проекцияларға қайта ойнатылуы.
«Үлкен жарылыстар» жасамаңыз - кері шегініп қадамдарға бөлшектеңіз.

Қауіпсіздікпен өзара байланыс

Scopes per version: v1/v2 үшін жеке OIDC-scopes/рөлдер.
Құпиялар/claim 's токені - келісімшарттың бір бөлігі; оларды ауыстыру = major.
PII/PCI - payload бағдарламасын қажетсіз кеңейтпеңіз; жаңа өрістер - ең аз артықшылықтармен.

Антипаттерндер

Swagger-wash: спецификациясы жаңартылды, сервер жоқ (немесе керісінше).
Protobuf-тегтерді қайта пайдалану - деректердің тыныш бұзылуы.
Majorсыз enum-мағыналарды ауыстыру.
Global '/v2 '«косметика үшін»: сыну фактісінсіз нұсқа.
sunset/usage-метриктер ұмытып кетті: ескі нұсқасын қауіпсіз түрде түсіру мүмкін емес.
Түрлі major үшін бір ортақ топик: реттер мен кілттерді араластыру.

Шығару алдындағы чек парағы

• Өзгерістер аддитивті немесе жеке major-сызық дайындалған.
• Линтерлер мен schema-diff жасыл (breaking өткен жоқ).
• SDK/мысалдар/құжаттар, үйлесімділік туралы түсіндірмелер жаңартылды.
• Клиенттерде tolerant reader қосылған; enum-fallback сынақтан өтті.
• major үшін - dual-run жоспары, адаптерлер, канарейка, sunset-даталар және тарату.
• Метриктер/логтар/трейлерлер ол бойынша нұсқаны және сегменттеуді қамтиды.
• v1, v2 салыстыру үшін стенд және алтын жиынтықтары бар.
• Оқиғалар үшін - BACKWARD/FULL режиміндегі схемалар тізілімі, топтастыру кілттері өзгермейді.

Үлгі үлгілері

REST (URI + negotiation)

Бағыт: '/api/v2/orders/{ id} '

Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`

Deprecation: `Sunset: 2026-06-30`, `Link: ; rel="alternate"`

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Events

`payment. captured. v2 '(өзек) және' payment. enriched. v2 '(егжей- тегжейі).
Өтпелі кезеңге продюсерден 'v1' және 'v2' келеді.

FAQ

'/v2 'қашан қажет?
Инварианттар/семантика өзгерген кезде, өрістер/әдістер жойылады, идентификаторлардың пішімі, партиялану кілті, SLA/таймингтер өзгеріп, клиенттер бұзылады.

REST бағдарламасында анық нұсқасыз өмір сүруге бола ма?
Тек ұсақ жүйелер үшін. Сыртқы интеграция үшін - айқын major-желілер жақсы.

Ескірген нұсқаны қанша уақыт сақтау керек?
Экожүйеге байланысты. Сыртқы әріптестер үшін әдетте ерте хабарлау және канарейка арқылы 6-12 ай.

Оқиғаларды нұсқалаудың API-ден айырмашылығы неде?
Оқиғалар - append-only; жаңа семантика = жаңа '.v2' және dual-emit түрі. Партияландыру кілті - келісімшарттың бір бөлігі.

Жиынтық

Нұсқалау стратегиялары - бұл процесс пен құралдар: әдепкі аддитивті эволюция, айқын major-сызықтар, capability-negotiation, dual-run және sunset. Бұған автоматты үйлесімділік, телеметрия және құжаттама тәртібін қосыңыз - және сіздің API-ларыңыз тез дамиды, «түнгі көші-қонсыз» және клиенттерде күтпеген құлдыраусыз.