Технология ва инфрасохтор → Версияи API

Версияи API

1) Чаро ба шумо лозим аст

• хатари ҳодисаҳоро ҳангоми релизҳо коҳиш медиҳад,
• ба шумо имкон медиҳад, ки такмил ва бехатариро ба нақша гиред,
• ба корхонаҳо мӯҳлатҳои пешгӯишавандаи муҳоҷирати шариконро медиҳад.

2) Таснифи тағйирот

PATCH (вайрон намешавад): ислоҳот бидуни тағир додани шартнома (илова кардани майдонҳои ихтиёрӣ, ислоҳи тасдиқкунӣ).
MINOR: васеъшавии қафо мувофиқ (нуқтаҳои нав, майдонҳо бо нобаёнӣ).
MAJOR (шикастан): тағир додани сохтор, семантика ё нест кардани майдонҳо/нуқтаҳои ниҳоӣ.

Semver 'MAJOR тавсия дода мешавад. МИНОР. PATCH 'барои артефактҳо (SDK/схемаҳо), дар ҳоле ки рақами "беруна" API метавонад содда карда шавад (v1, v2).

3) Моделҳои версионии REST

1. URI:

'GET/v1/payments/{ id}'

Тарафдор: шаффоф, кабелӣ, масири осон. Омӯз: такрори ҳуҷҷатҳо, таҳаввулоти нозуктар мушкилтар аст.

2. Дар сарлавҳаҳо (гуфтушунидҳои мундариҷа):

'Қабул кунед: ариза/внд. ширкат. пардохтҳо. v2 + json '

Тарафдор: чандирӣ, ҳеҷ "партов" дар URL, таҳаввулоти қулайи навъи ВАО. Омӯз: дар браузер ислоҳ кардан мушкилтар аст, ба шумо мизоҷи интизомӣ лозим аст.

3. Дар сарлавҳаи фармоишӣ:

'X-API-Version: 2' (или 'Апи-Версия: 2025-09-01')

Тарафдор: танҳо дар шлюз. Омӯз: стандартӣ нест, эҳтиёт бо кэш.

4. Нусхаи сана:

Хуб барои fintech/ҳисоботдиҳӣ: "буридани" пешгӯишавандаи тағирот (масалан. семоҳа).

5. Версияи захиравӣ/намунавӣ:

Тавсия: барои ҳамгироии беруна - 'URI vN' + Сарлавҳаҳои рад/ғуруби офтоб; барои дохилӣ - шумо метавонед 'Қабул кунед' ё сарлавҳаи версия, агар дарвоза ва платформа онро дастгирӣ кунад.

4) Диаграммаи QL

Афзалият - версияҳои глобалӣ нестанд. Таҳаввулот тавассути илова кардани майдонҳо/намудҳо ва фарсудашавӣ ('@ deprecated (сабаб:... "")').
Тағиротро вайрон кунед - танҳо дар тирезаҳои "калон" (фазои номбаршудаи схема) бо дастури муҳоҷират.
"n + 1" -ро тамошо кунед ва маънои майдонҳои мавҷударо тағир надиҳед.

5) GRPC/Протобуф

Рақамҳои саҳроӣ тағйирнопазиранд. Майдонҳои ҳазфшударо ҳамчун 'захирашуда' ишора кунед.
Бо нобаёнии бехатар майдонҳоро ҳамчун ихтиёрӣ илова кунед.
Барои санҷиши мутобиқати автоматӣ шикастани/линтро истифода баред.
Бастаҳои версия/модулҳо: 'пардохтҳои баставӣ. пардохтҳои v1; '→'. v2 '.

6) Чорабинии API (EDA)

Нақшаи чорабинӣ ҳамон шартнома аст. Онро дар Феҳристи Схема нигоҳ доред (Avro/JSON-Schema/Protobuf).
Мавзӯъҳо ва версияҳо: 'пардохтҳо. v1. пардохтҳои ваколатдор ','. v2 нест. ваколатдор '.
Тағйироти шикастагӣ - навъи ҳодиса ё мавзӯи нав.
Кафолати эволютсия: барои истеъмолкунандагон дар давраи LTS ба қафо мувофиқ аст.

7) Сиёсати депрессия ва EOL

• Амортизатсия: тамғакоғазҳо дар changelog ва мушаххасот (Open
• 'Депрессия: то ҳадди имкон' ғуруби офтоб: Сешанбе, 31 марти 2026 00:00:00 GMT '.
• Иртибот: портали почтаи электронӣ/шарикӣ, огоҳиномаҳои webhooks, қайдҳо.
• Истилоҳот: МИНОР - 3-6 моҳи дастгирӣ, МАЙОР - 9-18 моҳ (вобаста ба танқид).
• Тирезаҳои вақт: ислоҳ дар "Сиёсати тақвияти API".

8) Масир ва релизҳо

Дарвозаи API (Kong/Apigee/Nginx/Envoy): қоидаҳо аз рӯи префикс '/v1/', сарлавҳа ё mediatype.

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

Canary/Blue-Green/Shadow: версияи навро дар 1-5% трафик печонед, ченакҳо ва гузоришҳои хатогиҳои шартномаро муқоиса кунед.
Парчамҳои хусусият: Бе тағир додани шартнома рафторро пинҳон кунед.
Муҳоҷирати сифрӣ: бо MAJOR, схемаи маълумотро дучанд навиштан/хондан таъмин кунед.

9) Санҷиши шартнома ва назорати мутобиқат

Кушодани API Diff (ё swagger-diff) - Санҷед, ки MINOR/PATCH схемаҳоро вайрон намекунад.
Линтинги спектралӣ - услуб, метамаълумоти зарурӣ (версия, Deprecation).
Шартномаҳои истеъмолкунанда (Пакт) - кафолат медиҳад, ки провайдер муштариёнро вайрон намекунад.
buf шикастани dlya protobuf.
CI бояд ба шикастани тағирот бидуни баланд бардоштани MAJOR афтад.

10) Ҳуҷҷатгузорӣ ва SDK

Версияи хусусиятҳои: '/docs/api/v1/openapi. json ', '/docs/api/v2/...'.
Тавлиди SDK аз рӯи версия (npm/maven/pypi) бо Semver ва changelog.
Усулҳои фарсудашударо дар SDK бо шарҳи/Deprecated қайд кунед.

11) Мушоҳида аз рӯи версия

• RPS/ниҳонӣ/хатогиҳо дар як версия (нишони 'api _ version').
• Харитаҳои истифодаи Endpoint: Боз кӣ дар v1 аст?
• Огоҳиҳо: "> 10% 4xx аз сабаби номувофиқатии шартнома", "муштариёни кӯҳна> X% пас аз T-сана".

12) Кэш ва версияҳо

Версияи транзитӣ қобилияти CDN-ро беҳтар мекунад.

• 'Фарқ: Қабул кунед, X-API-Version'.
• Семантикаи посухро дар MINOR тағир надиҳед, то калидҳои кэшро вайрон кунед.

13) Бехатарӣ

Версияро ба JWT рамзгузорӣ ё часпонед - версия бо дархост муайян карда мешавад, на нишона.
Рақамҳои васлкунии дохилиро ошкор накунед. Барои хабарҳои беруна "v1/v2" -ро истифода баред.
Дар MAJOR, санҷиши бознигарӣ, маҳдудиятҳо, ниқоби PII.

14) Муҳоҷират ва ёрдамчиёни худкор

"Дастури муҳоҷират v1 → v2" -ро нашр кунед: ҷадвали харитасозии майдон, дархостҳо/посухҳои намунавӣ, ҳолатҳои канорӣ.
Мо барои муштариён (CLI) линтерҳо пешниҳод менамоем, ки майдонҳои кӯҳнаро таъкид мекунанд.
Барои шарикони калон - қуттии қуттӣ бо ду версия ва маҷмӯаи озмоишӣ.

15) Анти-намунаҳо

"Абадӣ v1": набудани мӯҳлатҳо ва ченакҳои истифода.
Тағироти шикастани пинҳонӣ дар MINOR/PATCH.
"Версия дар сатри дархост" ('? v = 2 ') - кэш ва хонишро мешиканад.
"Як нуқтаи ниҳоӣ сад арзиши парчам аст": озмоиш/ҳуҷҷат душвор аст.

16) Рӯйхати санҷиши амалисозӣ

1. Модели интихобшуда (URI/Қабул/Сарлавҳа) барои муштариёни беруна ва дохилӣ.
2. Semver барои мушаххасот ва SDK, санҷиши автоматӣ дар CI.
3. Қолабҳои сиёсати амортизатсия/ғуруби офтоб.
4. Масири дарвоза + канарейкаҳо, панели панелҳо аз рӯи версия.
5. Санҷишҳои CDC/Шартнома барои ҳамгироии муҳим (пардохтҳо, KYC, ҳисоботдиҳӣ).
6. Ҳуҷҷатгузорӣ/Дастури SDK/муҳоҷират ҳамзамон бо нашр нашр карда мешавад.
7. Нақшаи EOL бо сана ва масъулият.

17) Намунаҳо

17. 1 ИСТИРОҲАТ (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 Музокироти мундариҷа

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

17. 3 Диаграммаи QL (Ихтисороти саҳроӣ)

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

17. 4 GRPC (протобуф)

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. мувозинат. навсозӣ '
• 'wallet. v2 нест. мувозинат. тағир ёфт '(чорабинии нав бо схемаи васеъ)

Схемаҳо дар Феҳрист нигоҳ дошта мешаванд, продюсер чорабиниҳоро бо схемае, ки мутобиқатро вайрон мекунад, нашр намекунад.

18) Контекст IGaming/fintech (амалия)

Пардохтҳо: вуруди v2 барои PSP-ҳои нав, ки дар он 'вазъ '/' redup _ reasion' дароз карда мешавад; дар дарвоза, харитасозии v1 → v2 барои ҳисобот.
KYC: MINOR майдони 'pep _ screening' -ро илова мекунад, муштариён v1, v2 - талаб мекунанд.
Бозиҳо/маҳдудиятҳои масъул: MAJOR модели маҳдудиятҳоро тағйир медиҳад (ҳар рӯз/ҳафта). Содироти дукарата ба гузориш пеш аз EOL v1.
Ҳисобот ба танзимгарон: версияҳои муқарраршуда: 'ҳисобот-2025-01'.

19) Мини-сиёсат (намуна барои вики)

Модел: барои API-ҳои беруна - 'URI/vN/'; барои дохилӣ - 'Қабул кунед:... vN + json 'ё' X-API-Version: N '.
Semver: Мушаххасот ва SDK-ҳо ҳамчун 'N нашр карда мешаванд. ноболиғ. ямоқи '. MAJOR RFC/ADR-ро талаб мекунад.
Мутобиқат: MINOR/PATCH - ягон тағйироти шикаста нест. Шикастан → танҳо тавассути MAJOR.
Амортизатсия/EOL: ≥ эълони 90-рӯза; Санаи ғуруби офтоб дар сарлавҳаҳо; Филиали LTS барои муштариёни интиқодӣ.
Назорат: Кушода кардани API diff/buf дар CI, CDC барои ҳамгироии калидӣ.
Мушоҳида: ченакҳо/гузоришҳо бо нишони 'api _ version'.
Релизҳо: канарӣ 5% ≥ 24 соат, баъд аз марҳила то 100% бо ченакҳои сабз.

Натиҷа

Версия на дар бораи "/v2 дар URL ", балки дар бораи раванд аст: қоидаҳои возеҳи эволютсия, санҷиши мутобиқати автоматӣ, версияҳои идорашаванда ва эҳтироми ҳамгироӣ. Сиёсати возеҳро ворид кунед, мониторинг ва мушоҳидаҳоро автоматӣ кунед - ва тағирот дигар барои маҳсулот таҳдид нахоҳанд кард.