Технология жана инфраструктура → API версиясы

API версиясы

1) Эмне үчүн керек

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

2) Өзгөрүүлөрдү классификациялоо

PATCH (сындырбаган): келишимди өзгөртпөстөн оңдоолор (кошумча талааларды кошуу, валидация фикстери).
MINOR (кеңейтүү): back-compatible узартуу (жаңы end-point, талаалар менен default).
MAJOR (сындыруучу): түзүмүн өзгөртүү, семантика же талааларды/endpoints алып салуу.

SemVer 'MAJOR сунушталат. MINOR. PATCH 'артефакттар үчүн (SDK/схемалар), ошол эле учурда "тышкы" API номери жөнөкөйлөштүрүлүшү мүмкүн (v1, v2).

3) REST чыгаруу моделдери

1. URI БОЮНЧА:

`GET /v1/payments/{id}`

Артыкчылыктары: ачык-айкын, кэш, жонокой багыттоо. кемчиликтери: документтерди кайталоо, татаал кылдат иштеп чыгуу.

2. Аталыштарда (content negotiation):

`Accept: application/vnd. company. payments. v2+json`

Артыкчылыктары: ийкемдүүлүк, URLде "таштандынын" жоктугу, медиатиптин ыңгайлуу эволюциясы. Кемчиликтери: браузерде дебат кылуу кыйыныраак, тартиптүү кардар керек.

3. Кастомдук аталышта:

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

Артыкчылыктары: жөн гана шлюзда. Кемчиликтери: стандарттуулук жок, кэш менен этият.

4. Version-Date (date-based):

fintech/отчеттуулук үчүн жакшы: өзгөрүүлөрдүн алдын ала "кесип" (мисалы, чейрек сайын).

5. Ресурстун/моделдин версиясы:

Сунуш: тышкы интеграция үчүн - 'URI vN' + Deprecation/Sunset аталыштары; ички үчүн - Сиз 'Accept' же аталышы версия, эгерде шлюз жана платформа аны колдойт.

4) GraphQL

артыкчылык - эч кандай дүйнөлүк нускалары. Талааларды/түрлөрдү кошуу жана деприкация аркылуу эволюция ('@deprecated (reason: ""...)').
Бузуучу өзгөрүүлөр - миграциялык гид менен "чоң" терезелерде гана (versioned schema namespace).
"n + 1" жана учурдагы талааларды meaning өзгөртүү үчүн эмес, байкоо.

5) gRPC / Protobuf

Талаа номерлери өзгөрбөйт. Алыскы талааларды 'reserved' деп белгилеңиз.
коопсуз default менен optional катары талааларды кошуу.
автоматтык шайкештикти текшерүү үчүн buf breaking/lint колдонуу.
Пакеттерди/модулдарды версиялаңыз: 'package payments. v1;` → `payments. v2`.

6) Event API (EDA)

Иш-чаранын схемасы - ошол эле келишим. Аны Schema Registry (Euro/JSON-Schema/Protobuf) сактаңыз.
Топиктер жана версиялар: 'payments. v1. authorized`, `payments. v2. authorized`.
Бузуучу өзгөрүүлөр - окуянын жаңы түрү же жаңы топик.
Эволюциянын кепилдиктери: LTS мезгилинде консумерлер үчүн backward-compatible.

7) Деприкация саясаты жана EOL

• Deprecation: белгилер changelog жана өзгөчөлүктөрү (OpenAPI/GraphQL SDL), аталышы
• 'Deprecation: true' жана мүмкүн болгондо 'Sunset: Tue, 31 Mar 2026 00:00:00 GMT'.
• Байланыш: email/partner порталы, webhooks-эскертмелер, release notes.
• Мөөнөтү: MINOR - 3-6 ай колдоо, MAJOR - 9-18 ай (критикалык көз каранды).
• Убактылуу терезелер: "API версиялоо саясаты".

8) Багыттоо жана релиздер

API Gateway (Kong/Apigee/Nginx/Envoy): '/v1/' префикси боюнча эрежелер, аталышы же медиатиби боюнча.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: 1-5% трафик боюнча жаңы версияны тоголотуп, контракттык каталардын көрсөткүчтөрүн жана логилерин салыштырыңыз.
Feature Flags: келишимди өзгөртпөстөн жүрүм-турумун жашыруу.
Zero-downtime көчүрүү: MAJOR кош жазуу/окуу (dual-write/read) маалымат схемасы менен камсыз кылуу.

9) Келишим-тестирлөө жана шайкештикти контролдоо

OpenAPI Diff (же swagger-diff) - MINOR/PATCH схемаларды бузбайт текшерип.
Spectral linting - стили, милдеттүү метадеректер (Version, Deprecation).
Consumer-Driven Contracts (Pact) - провайдер кардарларды бузбайт деп кепилдик берет.
buf breaking для protobuf.
CI MAJOR жогорулатуу жок бузуучу өзгөрүүлөр менен түшүп керек.

10) Документация жана SDK

Species чыгаруу: '/docs/api/v1/openapi. json`, `/docs/api/v2/…`.
SemVer жана changelog менен версия (npm/maven/pypi) боюнча SDK түзүү.
Эскирген ыкмаларды SDK аннотацияларына/Депрессияга белгилеңиз.

11) Observability версиясы боюнча

• RPS/жашыруун/версия каталар ('api _ version' label).
• Эндпоинттерди колдонуу карталары: v1 дагы ким?
• Alerty: "> 10% 4xx due to contract mismatch", "эски кардарлар> X% T-датасынан кийин".

12) Кэш жана версия

Жолдогу версия CDN кэштоону жакшыртат.

• `Vary: Accept, X-API-Version`.
• MINORдагы жооп семантикасын кэш-ачкычтарды сындыруу үчүн өзгөртпөңүз.

13) Коопсуздук

JWT версиясын шифрлебеңиз жана тиркебеңиз - версиясы токенди эмес, өтүнүчтү аныктайт.
Ички жыйнак номерлерин ачыкка чыгарбаңыз. Тышкы билдирүүлөрдө "v1/v2" колдонуңуз.
MAJORда валидацияны, лимиттерди, PII маскасын кайра карап чыгыңыз.

14) Миграция жана авто жардамчылар

"Migration Guide v1 → v2" басылмасын жарыялаңыз: талаа шайкештиги таблицасы, суроо/жооп мисалдары, edge-кейстер.
Кардарларга эскирген талааларды жарыктандыруучу линтерлерди (CLI) сунуштайсыз.
Ири өнөктөштөр үчүн - эки версиясы жана тесттик маалымат топтому бар sandbox.

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

"Түбөлүк v1": колдонуу мөөнөтү жана метрика жоктугу.
MINOR/PATCH жашыруун бузуучу өзгөрүүлөр.
"query string версиясы" ('? v = 2') - кэш жана окууга жөндөмдүүлүктү бузат.
"Бир эндпоинт - желектин жүз мааниси": тестирлөө/документтештирүү кыйын.

16) Киргизүү чек-тизмеси

1. Тышкы жана ички кардарлар үчүн модель (URI/Accept/Header) тандалып алынган.
2. Спецификация жана SDK үчүн SemVer, CI автоматтык breaking-текшерүү.
3. Deprecation/Sunset саясат жана байланыш шаблондору.
4. Gateway-багыттоо + канареялар, версиялар боюнча дашборддор.
5. CDC/Contract tests боюнча критикалык интеграция (төлөмдөр, KYC, отчеттуулук).
6. Документация/SDK/миграциялык гид релизи менен бир убакта жарыяланган.
7. даталар жана жоопкерчиликтүү менен EOL планы.

17) Мисалдар

17. 1 REST (URI + аталыштары)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 Content Negotiation

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (талаа деприкация)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 Окуя модели

• `wallet. v1. balance. updated`
• `wallet. v2. balance. changed '(өнүккөн схемасы менен жаңы окуя)

Схемалар Registry сакталат, продюсер шайкештикти бузган схемасы менен окуяларды жарыялабайт.

18) Контекст iGaming/Fintech (практика)

Төлөмдөр: 'status '/' decline _ reason' кеңейтилген жаңы PSP үчүн v2 киргизүү; отчеттуулук үчүн v1 → v2 маппинг шлюзунда.
KYC: MINOR 'pep _ screening' талаасын кошот, кардарлар v1 тоготпойт, v2 - талап кылат.
Жооптуу оюндар/лимиттер: MAJOR лимиттердин моделин өзгөртөт (күнүмдүк/жумалык). EOL v1 чейин отчет эки экспорт.
Жөнгө салуучу органдарга отчеттуулук: белгиленген версиялар-даталар: 'reporting-2025-01'.

19) Мини-саясат (wiki үчүн мисал)

Модель: тышкы API үчүн - 'URI/vN/'; ички үчүн - 'Accept:... vN + json' же 'X-API-Version: N'.
SemVer: Specifications жана SDK катары жарыяланган 'N. minor. patch`. MAJOR RFC/ADR талап кылат.
Шайкештиги: MINOR/PATCH - эч кандай бузуучу өзгөрүүлөр. Бузуучу → гана MAJOR аркылуу.
Deprecation/EOL: ≥ 90 күндүн ичинде жарыялоо; Баш макалаларда Sunset датасы; критикалык кардарлар үчүн LTS-бутагы.
Control: OpenAPI diff/buf breaking в CI, CDC үчүн негизги интеграциялар.
Observability: 'api _ version' этикеткасы менен метрика/логи.
Релиздер: canary 5% ≥ 24h, андан кийин этап-этабы менен 100% жашыл метр менен.

Жыйынтык

Версиялоо - бул "URLдеги/v2" жөнүндө эмес, процесс жөнүндө: эволюциянын так эрежелери, шайкештикти автоматтык текшерүү, башкарылуучу релиздер жана интеграцияны урматтоо. Түшүнүктүү саясатты киргизиңиз, көзөмөлдү жана байкоону автоматташтырыңыз - жана өзгөртүүлөр продукт үчүн коркунуч болуп калат.