Технология және инфрақұрылым → API нұсқасы

API нұсқасы

1) Бұл не үшін қажет

• релиздер кезінде оқыс оқиғалар қаупін төмендетеді,
• жақсартулар мен қауіпсіздікті жоспарлы енгізуге мүмкіндік береді,
• бизнеске серіктестердің көші-қонының болжамды мерзімдерін береді.

2) Өзгерістерді жіктеу

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

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. Нұсқа-күні (date-based):

Финтех/есептілік үшін жақсы: өзгерістердің болжамды «қималары» (мысалы, тоқсан сайын).

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) Оқиғалық 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/серіктес порталы, 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 - стиль, міндетті метадеректер (нұсқа, Deprecation).
Consumer-Driven Contracts (Pact) - провайдер клиенттерді бұзбайтынына кепілдік береді.
buf breaking для protobuf.
CI MAJOR көтермей-ақ бұзатын өзгерістер кезінде құлдырауы тиіс.

10) Құжаттама және SDK

'/docs/api/v1/openapi. json`, `/docs/api/v2/…`.
SemVer және changelog бағдарламаларымен (npm/maven/pypi) нұсқалары бойынша SDK жасаңыз.
Ескірген әдістерді SDK аңдатпаларымен/Deprecated деп белгілеңіз.

11) Нұсқалар бойынша Observability

• RPS/жасырындылық/нұсқа қатесі ('api _ version' белгісі).
• Эндпоинттерді пайдалану карталары: v1-де тағы кім бар?
• Ескертулер: «> 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-check.
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/финтех контексі (практика)

Төлемдер: 'status '/' decline _ reason' кеңейтілген жаңа PSP үшін v2 енгізу; есеп беру үшін mapping 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: спецификациялар мен SDK 'N. ретінде жарияланады. minor. patch`. MAJOR RFC/ADR талап етеді.
Сыйысымдылық: MINOR/PATCH - бұзатын өзгерістерсіз. Сыну → тек MAJOR арқылы.
Deprecation/EOL: ≥ 90 күн бұрын хабарландыру; Тақырыптағы Sunset күні; сыни клиенттер үшін LTS-тармағы.
Бақылау: негізгі интеграциялар үшін CI, CDC OpenAPI diff/buf breaking.
Observability: 'api _ version' белгісі бар метриктер/логтар.
Релиздер: canary 5% ≥ 24 сағат, содан кейін кезең-кезеңімен 100% жасыл метриктер кезінде.

Жиынтық

Нұсқалау - бұл «URL-дегі/v2» туралы емес, процесс туралы: эволюцияның айқын ережелері, үйлесімділікті автоматты тексеру, басқарылатын релиздер және интеграцияларды құрметтеу. Түсінікті саясатты енгізіңіз, бақылау мен қадағалауды автоматтандырыңыз - және өзгерістер өнімге қауіп төндірмейді.