Амалиётҳои API

(Қисм: Амалиёт ва идоракунӣ)

1) Мақсад ва принсипҳо

API "қабати амалиётӣ" -и экосистема мебошад: чизе, ки тавассути шартнома автоматӣ намешавад, ба кори дастӣ ва хатар табдил меёбад.

• Шартнома-аввал: аввал мушаххасот (Open
• Бехатарӣ бо нобаёнӣ: миқёси ҳадди аққал, TTL кӯтоҳ, TLS/имзоҳои мутақобила.
• Мушоҳидашаванда: ченакҳои ниҳоӣ ва SLA.
• Idempotent: Такрори бехатар.
• Ба ақиб мувофиқ: эволютсия бидуни тағироти "шикастан".
• Санҷиш: далелҳои криптографии тасдиқшуда (квитансияҳо).

2) Шартнома ва моделҳо (истинод)

Кушодани API барои ҳамоҳангсозии дархостҳо; AsyncAPI барои чорабиниҳо/webhooks.
Майдонҳои талабшаванда дар ҳар як манбаъ 'id', 'версия', 'created _ at', 'updated _ at', 'иҷорагир', 'минтақа', 'trace _ id' мебошанд.

Намунаи порчаи шартнома

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) Аутентификатсия, авторизатсия, миқёс

OAuth2/OIDC барои корбарон/шарикон муштарӣ-эътимоднома/JWT dlya S2S.
Соҳаҳо/нақшҳои захиравӣ: 'пардохтҳо. нависед ',' каталог. хонед ',' аудит. содирот '.
РЕБАК: дастрасӣ "аз рӯи моликият" (иҷорагир/ҳисоб/зер-ҳисоб).
Асрори JIT: аломатҳои кӯтоҳмуддат, ҳатмии дастгоҳ/subnet/минтақа.
Ҷойгиркунии дастгоҳ ва MTLS барои амалиётҳои муҳим (пардохтҳо, калидҳо).

4) Idempotence ва "маҳз як бор"

Idempotency-Key (сарлавҳа) + dedup by '(калид, ҳисоб, масир)' дар равзанаи TTL.
Outbox/CDC барои интишори чорабиниҳо - таҳвили кафолатнок.
Таъсири дақиқ як маротиба: Таъсири тараф тавассути маҷаллаи транзаксия ба даст оварда мешавад; такрор ба ҳамон "квитансия" оварда мерасонад ('quitipt _ hash').
Сиёсати такрорӣ: ақибнишинии экспоненсиалӣ, ҷиттер, тирезаҳои максималӣ.

5) Маҳдудиятҳо, квотаҳо, афзалият

Ҳудуди нархҳо: барои як калид/иҷорагир/масир/минтақа; "мулоим" (429) ва "сахт" (буридан).

Квотаҳо/буҷетҳо: сарпӯшҳои ҳармоҳа/ҳаррӯза, веб-сайтҳои 'Квота'

Истифодаи одилона: афзалияти иҷорагирон аз рӯи сатҳи хизматрасонӣ (тилло/нуқра/биринҷӣ).
Буферҳои дарида: таркишҳои кӯтоҳ бидуни таназзули ҳамсояҳо.

6) Пагинатсия, филтрҳо, намунаҳо

Курсор (фармоиши устувори po 'created _ at, id'), 'page _ size' ≤ 1000.
Намунаҳои буридаи вақт ('аз', 'ба', 'нишонаи обӣ') барои гузоришҳо/транзаксияҳо.
Филтри DSL: поляи сафедкардашуда, '? status =... & иҷорагир =... & минтақа =...'.
Мувофиқат ишора мекунад: 'snapshot _ at '/' as _ of' барои гузориш додани API.

7) Версия ва мутобиқат

Semver: 'v1', 'v1. 1 '(васеъшавӣ),' v2 '- танҳо дар роҳҳои нав/фазои ном.
Қоидаҳои эволютсия: танҳо тавассути равзана майдонҳо/арзишҳоро илова кунед, "беқурб ва нест кунед".
Санҷишҳои мутобиқат: "шартномаҳо-as-tests" (истеъмолкунанда).

8) Чорабиниҳо, веб-китобҳо ва квитансияҳо

Async/API мавзӯъҳо/сарборӣ/имзоҳоро тавсиф мекунад.

Сарлавҳа: HMAC/EdDSA, сарлавҳаҳои 'X-Signature', 'X-Nonce', 'X-Timestamp' (тирезаи танг)

Квитансияҳо: 'гирифтани _ hash' ва имзои DSSE оид ба рӯйдодҳои муҳим (пардохтҳо, тағироти RTP/лимит, рӯйхати нархҳо).
Retrai ва dedup: номутобиқатӣ аз рӯи 'idempotency _ key '/' event _ id'.
DLQ/карантин: гузоришҳои нодуруст/такрорӣ бо сабабҳо.

9) Риоя ва сифат

Нишонаҳо: 'trace _ id/span _ id' ҳатмӣ тавассути дарвоза/чорабиниҳои корӣ/webhooks.
Нишондиҳандаҳо: мавҷудият, p50/p95/p99, хатогӣ, меъёри такрорӣ, арзиши 1 к.
Гузоришҳо: сохташуда, асрори/PII; 'иҷорагир/минтақа/версияҳои' labels.
SLO/огоҳиҳо: Шароити ба SLO нигаронидашуда ва худкор-рунҳо (таваққуф/масир/бозгашт).

10) Хатогиҳо ва семантикаи вазъ

2xx - муваффақият (202 барои амалиёти асинхронӣ).
4xx - гуноҳи муштарӣ (422 - тасдиқ, 409 - низоъ/идемпотенсия, 429 - маҳдудиятҳо).
5xx - мушкилоти муваққатӣ.
Ҷисми хато: 'рамз', 'паём', 'trace _ id', 'ишора', 'retry _ after? '.
UX барои шарикон: ҷадвали "чӣ бояд кард" барои ҳар як хатогӣ.

11) Сиёсат-ҳамчун-код (OPA/ABAC)

Иҷозати мутамарказ: "кӣ/чӣ/дар куҷо/кай/чаро".
Сиёсатҳо дар Git, баррасии код, санҷишҳои CI (пеш аз парвоз: "оё сиёсат иҷозат медиҳад? »).
Чеки So 'D: "пардохт эҷод кунед" ≠ "тасдиқ кунед".

12) Амният, махфият, риояи

Кам кардани PII: токенизатсия/ниқобҳо, дастрасӣ ба ибтидоӣ танҳо тавассути ҷабҳаҳои тасдиқшуда.
Асрҳо: Vault/KMS, TTL кӯтоҳ, гардишҳо; манъ кардани сирри муштарак.
Шифргузорӣ: mTLS/TLS 1. 3, AES-GCM ҳангоми истироҳат, HSTS/PKP дар ҳолати зарурӣ.
Огоҳии ҳуқуқӣ - Маҳаллисозии маълумот/калидҳо дар як минтақа.
Гузоришҳои аудитӣ: WORM, Merkle-иловаро, DSSE-имзоҳо.

13) Амалиёт: SLI/SLO ва панелҳои панелӣ

• Мавҷудияти ҳар як масир/минтақа.
• p95 таъхири (хондан/навиштан).
• Муваффақияти webhooks (квитансияҳо), ақибмонии интиқол.
• Хатогӣ/Меъёри такрорӣ.
• Арзиши як дархости 1k ва egress.

SLO (мисол): 99. 95% дастрасӣ; p95 ≤ 120/250 мс; webhooks ≥ 99. 5 %/5 дақиқа; P1 MTTR ≤ 60 дақ.

14) Идоракунии тағирот (Релизҳо/Рӯйпӯшҳо)

Кабуд-Грин/Канария барои дарвозаҳо ва масирҳои муҳим.
Ficheflags барои рафтори бе озод.
Тавсеаи → Migrate → Шартнома барои схемаҳо ва сарборӣ.
Руны: Нашри бозгашт, Парчами ғайрифаъол, Масири дубора, Кэши оббозӣ.
Артефактҳо: тасвирҳо/зуҳуроти имзошуда, феҳристи версияҳо.

15) SDK, мизоҷон, қуттиҳои қуттӣ

SDK-ҳои расмӣ (TS/Java/Python/Go) бо ҳамон хатогӣ ва семантикаи такрорӣ.
Муҳити қуттии қуттӣ бо калидҳои санҷишӣ/сертификатҳо ва тренажерҳои PSP/KYC/мундариҷа.
Санҷишҳои шартномавӣ ба CI SDK, мутобиқати шабона дохил карда мешаванд.

16) Модели маълумот (соддакардашуда)

'api _ key' {id, иҷорагир, миқёс [], ttl, created_by}'

'rate _ plan' '{иҷорагир, квотаҳо {масир → cap}, паридан, афзалият}'

'request _ log' {trace _ id, маршрут, актер, idempotency_key?, мақом, latency_ms, минтақа, cost_unit}'

'webhook _ qurecipt' {event _ id, нуқтаи ниҳоӣ, ҳолат, кӯшишҳо, receipt_hash, имзо} '

'policy' '{версия, қоидаҳо, имзокунанда, dsse}'

17) RACI

18) Нишондиҳандаҳои сифат

Шартномаи Drift: 0 тағироти "шикастан" бидуни беқурбшавӣ.
Меъёри хатогии Idempotency: ≤ 0. 01%.
Муваффақияти Webhook: ≥ 99. 5%, ақибмонӣ p95 ≤ 60 с.
Auth Fail vs сӯиистифода: ҳиссаи блокҳои зараровар, садо ≤ сатҳи ҳадаф.
Cost/1k: назорат аз рӯи хатсайрҳо ва минтақаҳо (буҷа/cap-огоҳиҳо).
Қабули SDK: ҳиссаи трафик тавассути SDK-ҳои расмӣ.

19) Китобҳои бозии ҳодиса

Хӯшае 429/маҳдудиятҳо: баланд бардоштани ҳадди ақалл барои тилло, калидҳои "ғалоғула", пайвастшавӣ бо шарик.
WebhOOK Lag: зиёд кардани коргарон/гурӯҳҳо, афзалият додан ба навбатҳо, муваққатан хомӯш кардани вебхукҳои ихтиёрӣ.
Нархҳо Mismatch (каталог/FX/Андоз): муқоисаи версия, маъюбии қувваи кэш, баргардонидани артефакт, ҷуброн.
Қатъи PSP: гузариши масир, карантини амалиётҳои "хокистарӣ", такрорӣ.
Compromise API-калид: бозхонди фаврӣ, ротатсия, аудити 30 рӯзи охир.

20) Хусусияти IGaming/fintech

RTP/Маҳдудиятҳои API: танҳо агрегатҳо ва версияҳои профил; тағирот - бо квитансия.
Пардохтҳо/пардохтҳо: 202 + веб-китобҳои имзошуда; фармоиши idempotency калидӣ.
Шарикон: тарҳи табдилдиҳӣ, раҳоӣ аз баҳсҳо, гузоришҳои имзошуда.
Бозии масъул: Барои маҳдудиятҳо ва рӯйдодҳои RG "посбон API" -ро фош кунед.

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

• Шартномаи тавсифшуда (Open
• Танзими OAuth2/OIDC, миқёс, асрори JIT ва M TLS барои хатсайрҳои муҳим.
• Idempotency, retrai, DLQ ва карантин ҷорӣ карда шуданд.
• Caps/Квотаҳо/Афзалиятҳо ва огоҳиҳо.
• Саҳифабандии курсор, 'ҳамчун _ аз' намунаҳои пайваста.
• Сиёсати амортизатсия ва амортизатсия.
• Webhooks бо имзоҳо/квитансияҳо, такрорӣ ва тарҳҳо.
• Пайгирӣ/ченакҳо/гузоришҳо, SLO ва runes.
• Гузоришҳои WORM, имзоҳои DSSE, иловаро Merkle.
• SDK, қуттича, тренажерҳо, намунаҳои рамз ва чӣ гуна.

22) FAQ

Чаро 202 барои амалиёти тӯлонӣ?
Бо мақсади нигоҳ надоштани пайвастшавӣ ва таъмин намудани бозпас/квитансияи боэътимод тавассути webhook.

Оё ба шумо ҳам Open

Бале: ҳамоҳангсозии фармонҳо/дархостҳо, асин барои рӯйдодҳо/гуфтушунидҳои давлатӣ.

Чӣ гуна бояд тағиротро пешгирӣ кард?
Танҳо қоидаи изофӣ, беқурб кардан → риоя кардан → хориҷ кардан, шартномаи санҷиши муштариён.

Квитансияҳоро дар куҷо нигоҳ доштан мумкин аст?
Дар минтақаи WORM бо имзоҳо; 'receipt _ hash' ба муштарӣ баргардонида мешавад ва тибқи дархост тафтиш карда мешавад.

Хулоса: Амалиётҳо тавассути API интизоми шартнома ва амалиёт мебошанд: модели дастрасии қатъӣ ва аблаҳӣ, маҳдудиятҳо ва версияҳо, мушоҳида ва SLO, имзоҳо ва квитансияҳо. Қуттиҳои қуттиҳо ва SDK илова кунед - ва шарикон зуд, боэътимод ва пешгӯишаванда муттаҳид мешаванд ва корхонаҳо бидуни аз даст додани сифат ё мувофиқат миқёс мегиранд.