Վիրահատություններ API ինտերֆեյսի միջոցով

(Բաժին ՝ Վիրահատություններ և կառավարում)

1) Նշանակումներ և սկզբունքներ

API-ն էկոհամակարգի «վիրահատական շերտն» է, այն ամենը, ինչ չի ավտոմատացված պայմանագրի միջոցով, վերածվում է ձեռքի աշխատանքի և ռիսկերի։

Սկզբունքները

Medract-first: Առաջին անգամ (OpenAPI/JSON Schema/AsyncAPI), հետո։

Secure-by-international-ը 'նվազագույն կրճատումներ, կարճ TTL, mutual-TSA/ստորագրություններ։

Observable: end-to-end հետքեր և SLA չափումներ։

Idempotent: խոհարարը անվտանգ է։

Backwards-compatible: էվոլյուցիան առանց «կոտրող» փոփոխությունների։

Auditable: կրիպտոգրաֆիկորեն ապացուցված փաստերը (քվիտանացիաներ)։

2) Պայմանագիրը և մոդելները (հանրաքվե)

OpenAPI-ը nc-հարցումների համար։ AsyncAPI-ը իրադարձությունների/webhuks-ի համար։

Պարտադիր դաշտերը յուրաքանչյուր թողարկման մեջ '"id'," version "," created _ at "," corated _ at "," tenae "," region "," 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 օգտագործողների/գործընկերների համար։ client-credentials/JWT для S2S.
Սկոպները/ռեսուրսային դերերը '«payments»։ write`, `catalog. read`, `audit. export`.

ReBAC: հասանելիություն «սեփականության» (տենանտ/հաշիվ/sab-հաշիվ)։

JIT գաղտնիքները 'հակիրճ հոսանքներ, կառուցվածքի/ենթաօրենսդրության։

Device posture & mTSA-ը կրիտիկական վիրահատությունների համար (վճարումներ, բանալիներ)։

4) Idempotenty-ը և «ուղիղ-անգամ»

Idempotency-Key (վերնագիր) + dedup '(key, account, rome)' TTL պատուհանում։

Windobox/CDC-ը իրադարձությունների հրապարակման համար երաշխավորված առաքում է։

Exactly-once-effects-ը, կողմնակի էֆեկտները գրանցվում են գործարքային ամսագրի միջոցով։ կրկնօրինակը հանգեցնում է նույն «քվիտանիայի» («receipt _ hash»)։

Retry-քաղաքականությունը 'էքսպոնենցիալ back, ջիթթեր, առավելագույն պատուհաններ։

5) Լիմիտներ, քվոտաներ, առաջնահերթություն

Rate limits: per-key/tenant/route/region; «փափուկ» (429) և «կոշտ» (խցիկ)։

Քվոտաներ/բյուջեներ ՝ ամսական/ամենօրյա գլխարկներ, Webhuks 'WintaCapReached "։

Fox-use: Ծառայության մակարդակի տենանտների գերակայությունը (Gold/Silver/Bronze)։

Burst-Express: Կարճ աճը առանց հարևանների քայքայման։

6) Պագինացիա, ֆիլտրեր, նմուշներ

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.

Time-sliced նմուշները («from», «to», «watermark») ամսագրերի/գործարքների համար։

Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.

Consistency hinae: /« as _ of »ռեպորտային API-ի համար։

7) Տարբերակումը և համատեղելիությունը

SemVer: `v1`, `v1. 1 '(ընդարձակումներ), «v2» - միայն նոր ճանապարհներով/նյարդային սպեյսամներով։

Էվոլյուցիայի կանոնները միայն դաշտերի/արժեքների ավելացումն են, պատուհանի միջոցով «deprecate diremove» -ը։

Compatibility tes.ru: «պայմանագրեր-թեստ» (consumer-driven)։

8) Իրադարձություններ, Webhuks և quitantia

AsyncAPI-ն նկարագրում է/payload/ստորագրությունները։

Ստորագրությունը ՝ HMAC/EdDSA, վերնագրերը 'X-Signature "," X-Nonce "," X-Timestamp "(նեղ պատուհան)։

Քվիտանզիա (receip.ru): «receipt _ hash» և DSSE ստորագրությունը կրիտիկական իրադարձությունների վրա (վճարումներ, RTP/limits փոփոխություններ, ռուսական թերթիկներ)։

Retrai և dedup 'idempotency _ key '/« event _ id »։

DLQ/karantin 'ոչ որակավոր/կրկնվող հաղորդագրություններ պատճառների հետ։

9) Դիտողությունն ու որակը

Traces: պարտադիր «trace _ id _ id» նավերի/բիզնես իրադարձությունների/webhuks միջոցով։

Metrance: Հասանելիություն, p50/p95/p99, error-rate, retry-rate, cost per 1k։

Logs: Կառուցվածքային, առանց գաղտնիքների/PII; 07 'tenault/region/version "։

SLO/alerts: SLO կողմնորոշված պայմանները և ավտոմեքենաները (pause/re-rober/rollback)։

10) Սխալներ և արձանների իմաստություն

2xx - հաջողություն (ասինխրոն վիրահատությունների համար)։

4xx - հաճախորդի գինին (422-valivation, 407 - հակամարտություն/idempotention, 429-լիմիտներ)։

5xx - ժամանակավոր խնդիրներ։

Սխալների մարմինը '"code'," "," trace _ id "," hint "," retry _ after "։

UX-ը գործընկերների համար '«ինչ անել» յուրաքանչյուր սխալի համար։

11) Քաղաքականություն-կոդը (OPA/ABAC)

Կենտրոնացված հեղինականացում. <<ով/ինչ/որտեղ/երբ/ինչու>>։

Քաղաքական գործիչները Git-ում, կոորդինատները, CI թեստերը (pre-flight: "Արդյո՞ ք քաղաքականությունը թույլ կտա։ »).

SoD-chek: «Ստեղծել» ռուսական «հաստատել»։

12) Անվտանգություն, գաղտնիություն, կոմպլամենս

PII-նվազեցումը 'թունավորումը/դիմակները, առաջնային հասանելիությունը միայն հաստատված ջոբայի միջոցով։

Գաղտնիքները ՝ Vox/KFC, կարճ TTL, ռոտացիաներ; shared գաղտնիքների արգելք։

Կոդավորումը ՝ mTSA/TSA 1։ 3, AES-GCM at-rest, HSTS/PKP որտեղ տեղին է։

Jurisdiction-a.ru: Տվյալների տեղայնացումը/www.per region։

Ամսագրի ամսագրերը ՝ WORM, Merkle-reses, DSE ստորագրություններ։

13) Վիրահատություն ՝ SLI/SLO և dashbords

SLI (օրինակ)

Per-rope/region հասանելիությունը։

Լատինականությունը p95 (read/write)։

Ուեբհուկի հաջողությունը (քվիտանցիա), առաքման լագը։

Error-rate/Retry-rate.

Cost per 1k հարցումներ և egress։

SLO (օրինակ) 99։ Հասանելիության 95 տոկոսը; p95/120/250 ms; Webhuki 3599։ 5 %/5 րոպե; P1 MTTR 3560 ռուբլիներ

14) Փոփոխությունների կառավարումը (բացթողումները)

Blue-Green/Canary դռների և կրիտիկական երթուղիների համար։

Ֆիչեֆլագները վարքի համար առանց օրինագծի։

Expand no Migrate Proct-ը սխեմաների և payload-ի համար։

Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.

Արտեֆակտներ 'ստորագրված պատկերներ/մանիֆեստներ, ռուսական տարբերակներ։

15) MSK, հաճախորդներ, «ավազներ»

Պաշտոնական MSK (TS/Java/Python/Go) նույն սխալների և ռետալների սեմանտիկայով։

Sandbox-միջավայրը թեստային բեկորների/հավաստագրերի և PFC/KYC/բովանդակության պրովայդերների հետ։

Euract-tes.ru-ն ներառված է MSK CI-ում, nightly-համատեքստում։

16) Տվյալների մոդելը (պարզեցված)

`api_key` `{id, tenant, scopes[], ttl, created_by}`

`rate_plan` `{tenant, quotas{route→cap}, burst, priority}`

`request_log` `{trace_id, route, actor, idempotency_key?, status, latency_ms, region, cost_unit}`

`webhook_receipt` `{event_id, endpoint, status, attempts, receipt_hash, signature}`

`policy` `{version, rules, signer, dsse}`

17) RACI

18) Հատկության մետրերը

Medract Drift: 0 «կոտրող» փոփոխություններ առանց դեպրեսիայի։

Idempotency Error Rate: ≤ 0. 01%.

Webhook Success: ≥ 99. 5%, lag p95-60 C։

Auth Fail vs Abuse-ը չարամիտ բլոկների մասն է, աղմուկը բարձրակարգ մակարդակ է։

Cost/1k: վերահսկումը երթուղիներով և տարածաշրջաններով (բյուջեներ/kap-alerta)։

MSK Adoption: մասնաբաժինը կատարվում է պաշտոնական SDK-ի միջոցով։

19) Պլեյբուկի

Spike 429/limits 'բարձրացնել kap Gold-ի համար, trottling «աղմկոտ» տերմինալ, կապ գործընկերոջ հետ։

Webhair Lag: բարձրացնել workers/batchi, առաջնահերթություն հերթերը, ժամանակավորապես անջատել ալյումինե webhuks։

PriceMismatch (catalog/FX/Tax) 'տարբերակների իջեցում, քեշի ֆորս հաշմանդամություն, արտեֆակտը, փոխհատուցումը։

PMS Engage-ը 'միգրանտների փոխակերպումը, «մոխրագույն» գործարքների կարանտինը, վերամշակումը։

Compromise API-key-ը 'չարտոնված ակնարկ, ռոտացիա, վերջին 30 օրվա աուդիտ։

20) iGaming/fintech առանձնահատկությունները

RTP/Limits API 'միայն ագրեգատներն ու տարբերակները։ փոփոխությունները քվիտանացիաների հետ են։

Վճարումներ/վճարումներ ՝ 105 + webhuks ստորագրություններով; դիմադրություն բանալին։

Աֆֆիլիատներ 'հակադարձման, վեճերի ուղեկցորդ, ստորագրված զեկույցների համար։

Պատասխանատու խաղը 'ցուցադրեք guardrails API-ը սահմանների և RG իրադարձությունների համար։

21) Ներդրման չեկի ցուցակ

• Ռուսաստանի պայմանագիրը (OpenAPI/AsyncAPI), CI-validation և consumer-tes.ru։
• Տրամադրված են OAuth2/OIDC, սկուտերներ, JIT գաղտնիքները և mTSA-ը կրիտիկական երթուղիների համար։
• Ներդրվել է impotenty, retrai, DLQ և կարանտին։
• Լիմիտներ/քվոտաներ/գերակայություններ և գլխարկներ։
• Պագինացիա կուրսորներով, խորհրդատվական նմուշներով 'as _ of "։
• Տարբերակումը և Deprecation-քաղաքականությունը։
• Webhuki ստորագրություններով/քվիտանացիաներով, ակնարկներով և պապուպով։
• Հետադարձ/մետրեր/լոգներ, SLO և ռունա։
• WORM ամսագրեր, DSSE ստորագրություններ, Merkle-reses։
• MSK, sandbox, սիմուլյատորներ, կոդի օրինակներ և «how-to»։

22) FAQ

Ինչո՞ ւ է երկար վիրահատության համար նախատեսված։

Որպեսզի չկորցնենք կապը և ապահովեք հուսալի ռետրա/քվիտանիա վեբխուկի միջոցով։

Արդյո՞ ք երկուսն էլ կարիք ունեն OpenAPI և AsyncAPI-ի։

Այո 'www.nc թիմերի/հարցումների համար, async իրադարձությունների համար/պետությունների համակարգման համար։

Ինչպե՞ ս կարող ենք խուսափել կոտրիչ փոփոխություններից։

«Միայն ավելացման» կանոնը, deprecate www.observe-ը, հաճախորդների պայմանագիր-թեստերը։

Որտե՞ ղ պահել քվիտանացիաները։

WORM-ում ստորագրություններով, «receipt _ hash» -ը վերադառնում է հաճախորդին և ավարտվում է պահանջով։

Ռեզյումեներ ՝ API-ի միջոցով վիրահատությունները պայմանագրի և գործողության կարգապահությունն են 'մուտքի խիստ մոդել և գաղափարախոսություն, սահմաններ և վարկածներ, դիտողություններ և SLO, ստորագրություններ և քվիտանտներ։ Ավելացրեք ավազները և SDK-ը, և գործընկերները ինտեգրվելու են արագ, անվտանգ և կանխատեսելի, իսկ բիզնեսը մասշտաբվում է առանց որակի և կոմպլանսի։