מערכת אקולוגית API

(סעיף: מערכת אקולוגית ורשת)

1) מטרות ועקרונות

• אינטגרציה מהירה וצפויה (זמן לאינטגרציה).
• אמינות וסקלביליות (SLO, QOS, backpressure).
• בטיחות וציות (זכויות מינימום, ביקורת חשבונות).
• אבולוציה ללא התמוטטות (גרסאות, תאימות, פישפלאגים).

עקרונות: חוזה ראשון, מזעור נתונים, אידמפוטנטיות, יכולת תצפית לפי ברירת מחדל, ”שתי מהירויות” של שחרור (ליבה נגד ניסוי).

2) טקסונומיה של API

1. REST/HTTP - פעולות synchronous CROD/Command, idepotency-key, pagination/corsors.
2. GRPC/QUIC - לינה נמוכה, זרמים, פרוטוקולים בינאריים.
3. אירועים (פאב/סאב) - אירועי תחום ('הפקדה. ", התשלום. ',' גשר. ”,” סיכון. ').
4. הודעות הפוכות עם חתימות ומגשים מחדש.
5. GraphQL (מוגבל) - קריאות צבירה על פני חנויות מומשו.
6. ספריות, גרסאות, סטטוסים, מפתחות, מכסות.

רמות גישה: Public (שיטות מוגבלות/קריאה), Partner (סקופים ומכסות), Internal (קווי מתאר פרטיים).

3) חוזים ותוכניות

OpenAPI/ASyncAPI/Protobuf IDL הוא מקור אמת יחיד.
חוזי נתונים - מבחני תאימות, קווי מעגל, איסור על "שבירת" שדות ללא מייג "ור.
קטלוגים: נכסים/רשתות, PSP/שיטות, אזורים/תחומי שיפוט, גרסאות SDK, דגלי יכולת.

חוזה מנוחה מינימלי (מקטע 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) ורסינציה ותאימות

סימוור: "מייג 'ור. מינורי. טלאי '. מינור/תיקון - לאחור-תואם; סרן - גרסאות מקבילות ('/v1 ', '/v2') + מתאם.
מדיניות דחייה: חלון 90 יום, שני קווי תמיכה, הודעה אוטומטית לחוזים.
מאפיין דגלים: אפשר/בטל שדות/שיטות על ידי אזור/שותף.
משא ומתן יכולת: הכרזת פרופילים נתמכים בעת לחיצת ידיים.

5) אידמפוטנטיות, פקודות וקללות

Idempotency-key לפקודות (ליצור/לבטל), מקשי TTL - 72 שעות.
בדיוק פעם אחת סמנטיקה באמצעות תיבת דואר אלקטרוני וצרכן אידמפוטנטי.
pagination by corsors: "next _ corress', התנגדות להכנסות/מחיקות.
מיון ומסננים יציבים, מתועדים בבירור.

6) ביטחון ואמון

MTLS (service↔service), פינג של שרתים וסיבוב מפתח.
OAuth2/OIDC (אישורי לקוח, JWT עם TTL קצר), PoP/DPoP לכריכה לערוץ.
חתימות Webhook (NMAS/key version/time), הגנה על חזרות.
RBAC/ABAC ו ־ POLP: סקופים, org_id/tenant_id, מגבלות על אובייקט/פעולה.
מזעור DLP/PII: איסור PII בתוויות/יומנים, סימון זהויות.
דרגה-גבולות ו-WAF: לכל מסלול/מסלול/אזור, הגנה לרעה.

מדיניות מפתח מדגם (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 ותרמיל גב

מחלקות QOS: P0 (תשלומים/ברידג '/פיניקליזציה), P1 (מוצר), P2 (כמות/ארכיון).
מכסות/גבולות: RPS, concur-בקשות, bytes/sec, נושא/צד לאירועים.
בקרת כניסה: דחייה מוקדמת של בקשות ”יקרות”, שמירה כבדה.
תרגיל גב: אסימונים/נקודות זכות, תורים עם DLQ, מגשים מחדש עם ג 'יטר.

מדיניות מכסה

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

8) יכולת תצפית: SLI/SLO, מדדים, עקבות

• P95/99 latency latency Drate, Success Rate, Avery Cuter Burn, Queue-lag p95, Fresness webhooks, Livership%.
• ציות לחוזים% (סכמות/חתימות).
• Webhook לנסות מחדש/ירד%.

P0 p95 400 גב ', זמינות 99. 95%; Webhook משלוח p95 lood 2 lember; אירועים רעננים פי 95 לפי 60.

מדדים: היסטוגרמות איחור, קודי שגיאה, גודל התגובות, RPS, לכל דייר.
עקבות: trace _ id מקצה לקצה (edge # gateway # service # DB # event/webhook).
יומנים: מובנים, ללא PII, מתאם על ידי "בקשה _ id'.

9) דפוסי שחרור ללא זמן

כחול-ירוק/קנרי עם שערי SLO ופליטה החוצה.
סכימה-ראשית אבולוציה: רק הוספת שדות, מתאם ללקוחות ישנים.
נדידת מסד נתונים בזמן אפס: DDL מקוון, ממירים דו כיווניים.
שינוי שליטה: טיימלוק, ביקורת רישום ותאימות.

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) בדיקה וציות לחוזים

מבחני חוזה: דור לקוחות, אימות סכימה, negative-_cases.
שידור חוזר של מבחני אירוע: התנגדות לחזרה/הזמנה מחדש.
כאוס/בדיקות לט: זריקות אובדן/ריגוש, סטור איטי.
בדיקות אבטחה: חתימות ברשת, סיבוב מפתח, התקפות שידור חוזר.
פרופילי ביצועים: קפיצות 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 - חוזה/גרסה/SLO/Quota.
אבטחה - מפתחות/חתימות/ביקורת/DLP.
SRE/Ops - לוחות מחוונים, התראות, קיבולת.
הצלחה שותפה, עלייה למטוס, גבולות, פישפלאגים.
ציות - סמכות שיפוט, סנקציות, דיווח.

14) לוחות מחוונים

Core API: Latency/IRPS על ידי מסלול ואוהל.
פתקי אינטרנט: משלוח p95, חזרה, טיפות, חתימות.
אירועים: רעננות, פיגור, בריאות הצרכן, די-אל-קיו.
אבטחה: מפתחות תפוגה, חתימות, בקשות נדחו.
ממשל: גרסאות פעילות/מדורגות, תאימות חוזה.

15) תקריות משחק

צמיחה של p95 Latency P0

1. אפשר P0 ועדיפות P2-throttle; 2) שערים בקנה מידה;

2. החלף חלק מהקריאה למטמון 4) ניתוח של מסלולים ”חמים”.

ב. מסירת ווב-הוק נופלת

1. בדוק חתימות/משמרת שעה, 2) הגדלת מגשים/פסקי זמן,

2. הפעל את חבורות, 4) זמנית לעבור לנקודת הקצה של הכדור.

חוזי דריפט C

1. אפשר ”מצב קפדני”

2. הודע למפיק, 3) שחרר את המתאם, 4) לאחר המוות, עדכן את הקווים.

ד. פשרת מפתח/סלט

1. ביטול/סיבוב, 2) שידור חוזר של ספרים, 3) ביקורת, 4) הודע לשותפים.

אי. חזור/קח פיצוץ

1. בדוק Idempotency-Key/TTL, 2) לחזק את המת, 3) להגביל את המקור ”רועש”.

16) רשימת מימושים

1. תאר חוזים (OpenAPI/ASyncAPI/IDL), כולל לינטרים ו ־ CI.
2. הגדרת auth (OAuth2/OIDC, mTLS), חתימות webhook, סיבוב מפתח.
3. הזן מכסות/מגבלות QOS/, שמירה כבדה ושמירת גב.
4. העלו את יכולת התצפית: SLI/SLO, מסלולים, לוחות מחוונים, התראות.
5. ארגון שחרור: כנרית/כחול-ירוק, נדודים סכימה-ראשון.
6. הפעל את תיקיית הגירסה/אירוע/מפתח ופחת תהליכים.
7. לבצע בדיקות אבטחה, לארגן ספרי משחק.
8. לשפץ באופן קבוע מזעור נתונים וציות רגולטורי.

17) גלוסרי

חוזה ראשון - עיצוב API דרך חוזים רשמיים לקוד.
Idempotency-מפתח - מפתח שהופך את הפעולה חזרה בבטחה.
AsyncAPI - מפרט של ממשקי אירועים.
QOS - איכות השירות/עדיפות כיתה.
DLQ - ”תור מת” להודעות בעיה.
שגיאה בתקציב השרפה - שיעור ה ”שריפה” בתקציב השגיאה ביחס ל ־ SLO.

שורה תחתונה: המערכת האקולוגית API אינה קבוצה של נקודות קצה, אלא מערכת מנוהלת של חוזים, ביטחון, מכסות ויכולת תצפית. על ־ ידי כך, המערכת האקולוגית משיגה אינטגרציה מהירה, סל "ד צפוי ואבולוציה בטוחה ללא השבתה - משכבת הרשת ואימות לאירוע זורמים ומדווחים.