API էկոհամակարգ

(Բաժին ՝ Էկոհամակարգ և ցանց)

1) Նպատակներն ու սկզբունքները

API էկոհամակարգը մասնակիցների (օպերատորներ, ստուդիաներ, PSA, KYC/AML, կամուրջներ, վերլուծություն) փոխազդեցության համար ստանդարտ ինտերֆեյսների շարք է։ Նպատակները

Արագ, կանխատեսելի (Time-to-integration)։

Գրանցումը և մեծացումը (SLO, QoS, backpressure)։

Անվտանգությունը և կարգավորողների պահպանումը (նվազագույն իրավունքները, աուդիտը)։

Էվոլյուցիան առանց կոտրվածքների (վարկածներ, համատեղելիություն, ֆիչեֆլագներ)։

Սկզբունքները ՝ www.ract-first, տվյալների նվազագույնի, գաղափարախոսություն, observability-by-international, ածխաջրածինների «երկու արագություն» (www.vs experimental)։

2) API տաքսոնոմիա

1. REST/HTTP - սինխրոն CRUD/թիմային վիրահատություններ, idempotency-key, pagination/cursors։

2. GRPC/QUIC-ը ցածր լատենտ է, ստրիմա, երկուական արձանագրություններ։

3. Events (Pub/Sub) - հիբրիդային իրադարձություններ («deposit. ',» payout.', «bridge. ',» risk.')։

4. Webhooks-ը հետադարձ ծանուցումներ է ստորագրությունների և ելույթների հետ։

5. GraphQL (սահմանափակ) - նյութականացված վիտրինի վերևում համակցող ընթերցումներ։

6. Admin/Meta - և, տարբերակները, կարգավիճակները, բանալիները, քվոտաները։

Հասանելիության մակարդակները ՝ Public (սահմանափակված մեթոդներ/ընթերցումներ), Partner (սկուտերներ և քվոտաներ), Mastal (մասնավոր ուրվագծեր)։

3) Պայմանագրեր և սխեմաներ

OpenAPI/AsyncAPI/Eurobuf IDL-ը ճշմարտության միակ աղբյուրն է։

Medracom-ը կոդավորման թեստեր են, սխեմաների ոսպնյակներ, «կոտրող» դաշտերի արգելք առանց MAJOR-ի։

Տյումենի 'ակտիվներ/ցանցեր, PSA/մեթոդներ, տարածաշրջաններ/իրավասություններ, MSK տարբերակները, հնարավորությունների դրոշները։

Նվազագույն REST պայմանագիրը (OpenAPI հատվածը)

yaml openapi: 3. 0. 3 info: { title: Ecosystem Core API, version: "2. 6. 0" }
paths:
/v2/payouts:
post:
operationId: createPayout parameters:
- in: header name: Idempotency-Key required: true schema: { type: string, maxLength: 64 }
requestBody:
required: true content:
application/json:
schema:
$ref: "#/components/schemas/PayoutRequest"
responses:
"202": { $ref: "#/components/responses/Ack" }
"409": { description: "Duplicate (idempotent)" }
components:
schemas:
PayoutRequest:
type: object required: [amount, currency, destination]
properties:
amount:  { type: string, pattern: "^[0-9]+(\\.[0-9]{1,9})?$" }
currency: { type: string, example: "USD" }
destination: { type: string }
metadata: { type: object, additionalProperties: true }

Իրադարձություններ (AsyncAPI)

yaml asyncapi: 2. 6. 0 info: { title: Ecosystem Events, version: "1. 9. 0" }
channels:
payout. finalized:
subscribe:
message:
name: PayoutFinalized payload:
type: object required: [id, ts, amount, currency, status, signature]
properties:
id: { type: string }
ts: { type: string, format: date-time }
amount: { type: string }
currency: { type: string }
status: { type: string, enum: ["finalized","failed"] }
signature: {type: string} # source signature

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

SemVer: `MAJOR. MINOR. PATCH`. MINOR/PATCH-ը միասին է։ MAJOR-ը զուգահեռ տարբերակներ է («/v1 », «/v2») + ադապտերներ։

Deprecation policy: Պատուհանը 90 օր է, աջակցության երկու գիծ, պայմանագրերով ավտոմատ ծանուցումներ։

Feature Flags: 108/դաշտի/մեթոդների անջատումը տարածաշրջաններում/108։

Capability Negotiation-ը 'ձեռքսեղմման ժամանակ աջակցվող հայտարարությունն է։

5) Idempotenty, դասեր և կուրսորներ

Idempotency-Key թիմերի համար (create/cancel), TTL 2472 ռուբլիներ

Exactly-once սեմանտիկան www.box/inbox և idempotent կոնսումերի միջոցով։

Պագինացիա կուրսորներով '«next _ cursor», ներդիրների դիմադրություն/հեռացում։

Տեսակավորումը և ֆիլտրերը կայուն, հստակ փաստաթղթավորված են։

6) Անվտանգությունն ու վստահությունը

MTSA (No. No.), մոխրագույն պիննինգ և լուծարումը։

OAuth2/OIDC (client credentials, JWT կարճ TTL), PoP/DPoP-ը դիմելու համար։

Webhook ստորագրությունները (NMAS/ստեղնաշարի/ժամանակի տարբերակը), պաշտպանություն խոհարարներից։

RBAC/ABAC և PoLP ՝ սկուտերներ, org _ id/tenrone _ id, օբյեկտի/վիրահատության սահմաններ։

DLP/PII նվազեցումը 'PII-ի արգելքը պիտակների/լոգարանների մեջ, ֆոսֆատորների թունայնացումը։

Rate-limits և WAF: per org/roult/region, պաշտպանություն abuse-ից։

Մրցույթի քաղաքականության օրինակ (YAML)

yaml auth:
oauth2:
issuer: "https://auth. ecosys"
jwks_uri: "https://auth. ecosys/.well-known/jwks. json"
token_ttl_s: 900 mtls:
required_for: ["internal","partner_p0"]
scopes:
- name: payouts:write
- name: payouts:read
- name: events:subscribe

7) Քվոտաներ, QoS և backpressure

QoS: P0 (վճարումներ/կամուրջ/վերջնական), P1 (ապրանքային), P2 (bulk/արխիվ)։

Քվոտաներ/լիմիտներ ՝ RPS, concur-reques.ru, bytes/sec, թեման/իրադարձությունների համար։

Admission corl '«թանկ» հարցումների վաղ շեղումը, heavy-query-guard։

Backpressure: towens/վարկեր, DLQ-ի հերթեր, ջիթերի հետ։

քվոտաների քաղաքականությունը

yaml quotas:
partner_default:
rps: 200 concurrent: 100 webhooks_outbound_rps: 50 p0:
rps: 100 p95_latency_ms: 400

8) Դիտարկումը 'SLI/SLO, մետրեր, հետքեր

SLI (միջուկը)

p95/99 latency по маршрутам, Success Rate, Error budget burn, Queue-lag p95, Freshness webhooks, Delivery success%.

Medract Compli.rom (սխեմաներ/ստորագրություններ)։

Webhook retry/dropped%.

SLO (կենտրոններ): P0 p95-400, Availability 2499։ 95%; Webhook delivery p95 ≤ 2 с; Events freshness p95 ≤ 60 с.

Մետրիկները ՝ լատենտության հիստոգրամներ, սխալների չափում, պատասխանների չափը, RPS, per-tenae։

Թրեյզներ ՝ «trace _ id» (edge wingateway) միջոցով։

Լոգները 'կառուցվածքային, առանց PII-ի, հարաբերակցությունը «request _ id»։

9) Ածխաջրածինների փաթթերները առանց դաունթայմի

Blue-Green/Canary-ի հետ SLO-gatts-ի և www.ier-eject-ի հետ։

Schema-first էվոլյուցիա 'միայն դաշտերի ավելացում, հին հաճախորդների ադապտերներ։

Zero-downtime-ը BD-ն է 'առցանց DDL-ն, երկվորյակ ծրարներ։

Փոփոխությունների վերահսկումը 'timelock, աուդիտ և ռուսական։

10) Պիտերբուրգը և Բուլգարները

API/տարբերակներ

sql
CREATE TABLE api_registry(
name TEXT, kind TEXT,      -- rest    grpc    events    webhook version TEXT, status TEXT,   -- active    canary    deprecated    retired slo JSONB, owner TEXT,
PRIMARY KEY (name, version)
);

Իրադարձությունների կատալոգը

sql
CREATE TABLE event_catalog(
topic TEXT PRIMARY KEY,
schema_version TEXT,
qos TEXT,
retention_days INT,
pii BOOLEAN DEFAULT false
);

Բանալիներ/սկուտերներ

sql
CREATE TABLE api_keys(
key_id TEXT PRIMARY KEY,
org_id TEXT, scopes TEXT[], status TEXT, expires_at TIMESTAMPTZ
);

11) Փորձարկումներ և պայմանագրերի համապատասխանություն

Medract-tes.ru 'հաճախորդների գեներացիա, սխեմաների վալիդացիա, negative- _ cases։

Իրադարձությունների Replay-թեստերը 'խոհարարների դիմադրությունը/վերարտադրումը։

Chaos/Lat-tes.ru: Pro/jitter, դանդաղ պատկեր։

Systement-tes.ru: Webhuks ստորագրությունները, կոդավորման վերացումը, պատմիչների հարձակումները։

Performant-պրոֆիլներ ՝ SLA-սպայկի, «տաք» երթուղիներ, DA/կախվածության կամուրջ։

12) Ինտերֆեյսների օրինակներ

Webhooks (ստորագրություն և գրանցումներ)

yaml webhooks:
deliveries:
retry:
attempts: 5 backoff_ms: [200, 800, 1600, 3200, 6400]
jitter: true signature:
alg: "HMAC-SHA256"
header: "X-ECO-Signature"
timestamp_header: "X-ECO-Timestamp"
tolerance_s: 300

GraphQL (համախմբող ընթերցումներ, միայն կարդալ)

graphql type Query {
payouts(status: [Status!], first: Int!, after: String): PayoutConnection!
}

gRPC (իրադարձությունների հոսք)

proto service EventStream {
rpc Subscribe(SubscribeRequest) returns (stream Event);
}

13) Գործընթացներ և դերեր

API Owner-ը/SLO/քվոտայի պայմանագիր է։

Մոսկվա - բանալիներ/ստորագրություններ/աուդիտ/DLP։

MSE/Ops - dashbords, alerts, capacity։

Partner Success-ը Onbording, limits, ficheflagy-ն է։

Compliance-ը իրավասություններ, սանկցիաներ, հաշվետվություններ է։

14) Դաշբորդի

Peter API: latency/error/RPS երթուղիներով և tentants-ով։

Webhooks: wwww.ivery p95, retries, drops, ստորագրություններ։

Events: freshness, lag, consumer health, DLQ.

Տե՛ ս ՝ ազատման, ստորագրության, մերժված հարցումների բանալիներ։

Governations: ակտիվ տարբերակներ/դեպրեքսներ, ինտեգրման համատեղելիություն։

15) Playbook 2019

A. Աճը P0

1. Ներառել P0 և P2-throtttle առաջնահերթությունները։ 2) չափել կողպեքները.

2. անցեք որոշ ընթերցումներ քեշի վրա։ 4) «տաք» երթուղիների վերլուծությունը։

B Անկում webhook

1. Ստուգել ստորագրությունները/ժամացույցի հերթափոխը, 2) բարձրացնել հետքերը/թայմաուտները,

2. միացրեք, 4) ժամանակավորապես անցնել էնդպոինտ գնդակին։

C. Drift of

1. Միացրեք «strict mode» (կտրել սխալ հաղորդագրությունները),

2. տեղեկացրեք արտադրողին, 3) թողարկել ադապտերը, 4) փոստի մորտը, նորարարել ոսպնյակները։

D. փոխզիջում ստեղնաշարի/սերտի

1. Revoke/rotate, 2) վերագտնել webhuks, 3) աուդիտ, 4) տեղեկացնել գործընկերներին։

E./դուբլի պայթյուն

1. Ստուգել Idempotency-Key/TTL, 2) ուժեղացնել պապուպը, 3) սահմանափակել «աղմկոտ» աղբյուրը։

16)

1. Նկարագրել պայմանագրերը (OpenAPI/AsyncAPI/IDL), ներառել ոսպնյակներ և CI։

2. Տեղադրեք auth (OAuth2/OIDC, mTSA), webhuks ստորագրությունները, միգրացիան։

3. Ներդրել քվոտաներ/QoS/limits, heavy-query-guard և backpressure։

4. Բարձրացնել դիտարկումը 'SLI/SLO, մայրուղիներ, dashbords, alerts։

5. Կազմակերպեք ֆորումներ 'canary/blue-green, schema-first 2019։

6. Սկսել տարբերակների/իրադարձությունների կատալոգը և ավանդների գործընթացները։

7. Անցկացնել chaos/perf/2019 թեստեր, պլեյբուսներ։

8. Պարբերաբար ստուգել տվյալների նվազեցումը և կարգավորիչի համապատասխանությունը։

17) Գլոսարիա

Euract-first-ը API-ի նախագծումն է պաշտոնական պայմանագրերի միջոցով կոդի։

Idempotency-Key-ը բանալին է, որը դարձնում է վիրահատության ուսուցիչը անվտանգ։

AsyncAPI-ը իրադարձական ինտերֆեյսների առանձնահատկությունն է։

QoS-ը որակի դասն է/ծառայության գերակայությունը։

DLQ-ը «մեռած հերթն» է խնդրահարույց հաղորդագրությունների համար։

Error budget burn-ը SLO-ի հետ կապված սխալների բյուջեի «այրման» արագությունն է։

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