פעולות API

(סעיף: מבצעים וניהול)

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

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

• חוזה-ראשון: מפרט ראשון (OpenAPI/JSON Schema/AsyncAPI), ולאחר מכן יישום.
• מאובטח כברירת מחדל: סקופים מינימליים, TTL קצר, TLS/חתימות הדדיות.
• ניתן לצפייה: איתור מקצה לקצה ומדדי SLA.
• שידור חוזר בטוח.
• התאמה לאחור: אבולוציה ללא ”שבירה” שינויים.
• שמיעה: עובדות מאומתות באופן קריפטוגרפי (קבלות).

2) חוזה ומודלים (התייחסות)

OpenAPI לבקשות סינכרון; AsyncAPI לאירועים/ספרים באינטרנט.
שדות נדרשים בכל משאב הם ”id',” version ”,” creed _ at ”,” updated _ at ”,” terrace _ 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 S2S.
תפקידי סקופים/משאבים: תשלומים. לכתוב ',' קטלוג. לקרוא, ביקורת חשבונות. ייצוא ".
REBAC: גישה ”על ידי בעלות” (דייר/חשבון/תת-חשבון).
סודות JIT: אסימונים קצרי ימים, התקן/תת רשת/קשירת אזור.
יציבת התקן & mTLS לפעולות קריטיות (תשלומים, מפתחות).

4) אידמפוטנטיות ו ”בדיוק פעם אחת” ‏

Idempotency-Key (כותרת) + dedup by '(מפתח, חשבון, מסלול) בחלון TTL.
יוצא מן הכלל/המרכז לבקרת מחלות לפרסם אירועים - משלוח מובטח.
בדיוק-פעם-תופעות: תופעות לוואי נתפסות דרך יומן עסקה; חזרות מובילות לאותה ”קבלה” (”קבלה _ חשיש”).
מדיניות חזרה: גיבוי מעריכי, ג 'יטר, חלונות מקסימליים.

5) מגבלות, מכסות, עדיפות

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

6) עבודת אלילים, מסננים, דוגמאות

Corresor-based (הזמנה יציבה "נוצר _ at, id')," page _ size "like 1000.
דוגמאות פרוסות זמן ("מ", "עד", "watermark" ") עבור יומנים/עסקאות.
סינון DSL: whitelship loughter ','? status =...
רמז עקביות: "snapshot _ at'/" as _ of" לדיווח API.

7) ורסינציה ותאימות

Semver: 'v1', 'v1. 1 '(תוספות),' v2 '- רק על נתיבים/אספנות שם חדשים.
כללי אבולוציה: הוספת שדות/ערכים בלבד, ”הסר” דרך החלון.
מבחני תאימות: ”חוזים כמבחנים” (מונע על ידי צרכנים).

8) אירועים, פתקי אינטרנט וקבלות

AsyncAPI מתאר את הנושאים/מטען/חתימות.

כותרת: HMAC/EdDSA, כותרות ”X-חתימה”, ”X-Nonce”, ”X-Timestamp” (חלון צר)

קבלות: ”קבלה _ חשיש” וחתימה DSSE על אירועים קריטיים (תשלומים, שינויי RTP/הגבלה, רשימות מחירים).
Retrai and dedup: idempotency על פי "idempotency _ key "/" event _ id'.
DLQ/הסגר: דיווחים לא תקפים/חוזרים עם סיבות.

9) יכולת תצפית ואיכות

עקבות: trace _ id/span _ id דרך שער/אירועים עסקיים/webhooks.
מדדים: זמינות, p50/p95/p999, שיעור שגיאה, שיעור חזרה, עלות ל-1k.
יומנים: מובנים, ללא סודות/PII; דייר/אזור/גירסה.
SLO/התראות: SLO-מונחה תנאים ורונות אוטומטיות (pause/re-road/rollback).

10) שגיאות וסמנטיקה סטטוטורית

2xx - הצלחה (202 לפעולות אסינכרוניות).
4xx - אשמת הלקוח (422 - אימות, 409 - סכסוך/אידמפוטנטיות, 429 - גבולות).
5xx - בעיות זמניות.
גוף שגיאה: ”קוד”, ”הודעה”, ”trace _ id”, ”רמז”, ”retry _ after”? '.
UX לשותפים: טבלה של ”מה לעשות” לכל שגיאה.

11) מדיניות כקוד (אופ "א/ABAC)

אישור מרוכז: ”מי/מה/איפה/מתי/למה”.
מדיניות בגיט, סקירת קוד, בדיקות מודיע (טרום טיסה: "האם המדיניות תאפשר? »).

בדיקת SoD: ”ליצור תשלום” לאשר ”.”

12) ביטחון, פרטיות, ציות

מזעור PII: tokenization/masks, גישה לראשית רק דרך דקירות מאושרות.
סודות: כספת/KMS, TTL קצר, סיבובים; איסור על סודות משותפים.
הצפנה: mTLS/TLS 1. 3, AES-GCM במנוחה, HSTS/PKP במקום המתאים.
תחום שיפוט מודע - לוקליזציה של נתונים/מפתחות לכל אזור.
יומני ביקורת: תולעת, פרוסות מרקל, חתימות DSSE.

13) מבצע: SLI/SLO ולוחות מחוונים

• זמינות לכל מסלול/אזור.
• p95 latency (קריאה/כתיבה).
• הצלחה של חוברות אינטרנט (קבלות), פיגור משלוחים.
• שגיאה-קצב/Retry-Rate.
• עלות לכל 1 k בקשות ויציאה.

SLO (דוגמה): 99. זמינות של 95%; p95 פר 120/250; מחברות אינטרנט 99. 5 %/5-דקות; P1 MTTR על 60 דקות.

14) ניהול שינוי (שחרור/רולבקס)

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

15) SDK, לקוחות, ארגזי חול

SDKs רשמי (TS/Java/Python/Go) עם אותה שגיאה ומגש מחדש.
סביבות ארגז חול עם מפתחות בדיקה/תעודות וסימולטורים מספקי תוכן PSP/KYC.
מבחני החוזה כלולים ב-CI SDK, תאימות לילית.

16) מודל נתונים (מפושט)

”api _ key” [דייר, scopes [ ], tl, tl, created_by}'

”rate _ plane” ”.דייר, מכסות [מסלול] cap, פרץ, עדיפות”

'request _ log' '_ trace _ id, מסלול, שחקן, idempotency_key?, מעמד, latency_ms, אזור, cost_unit}'

webook _ respont' event _ id, endpoint, status, states, receipt_hash, חתימה '

'Pollicy' [גרסה, כללים, חותם, dsse] "

17) ראסי

18) מדדים איכותיים

סחיפת חוזה: 0 ”שבירת” שינויים ללא הפחתה.
שיעור שגיאת אידמפוטנטיות: 0. 01%.
הצלחה Webhook: 99. 5%, lag p95 stage 60 s.
Auth Fail נגד Abuse: נתח של בלוקים זדוניים, רעש בקומת היעד.
Cost/1k: שליטה על ידי נתיבים ואזורים (תקציבים/התראות).
אימוץ SDK: נתח של תנועה באמצעות SDKs רשמיים.

19) חוברות משחק תקריות

ספייק 429/limits: להעלות כובע עבור זהב, לחנוק ”רועש” מפתחות, חיבור עם שותף.
WebhalLag: להגדיל עובדים/חבורות, לתעדף תורים, באופן זמני לכבות קורות אינטרנט אופציונליות.
Mismatch (קטלוג/FX/Tax): פיוס גרסה, נכות בכוח מטמון, רולבק חפץ, פיצוי.
החלפת מסלול, הסגר על עסקאות ”אפורות”, שידור חוזר.
פשרה מפתח API: זכרון מיידי, סיבוב, ביקורת של 30 הימים האחרונים.

20) מפרט של iGaming/fintech

RTP/Limits API: רק אגרגטים וגרסאות פרופיל; שינויים עם קבלות.
תשלומים/תשלומים: 202 + ספרי אינטרנט חתומים; להזמין אידמפוטנטיות מפתח.
השתייכות: dedup המרה, נאמנות למחלוקות, דוחות חתומים.
משחק אחראי: לחשוף ”מעקות בטיחות API” עבור גבולות ואירועי RG.

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

[ ] מתואר חוזה (OpenAPI/ASyncAPI), אימות CI ומבחני צרכנים.

[ ] הגדירו OAuth2/OIDC, סקופים, סודות JIT ו-MTLS למסלולים קריטיים.

[ ] אידמפוטנטיות, רטריי, די-אל-קיו והסגר.

[ ] Caps/Quotas/סדרי עדיפויות והתראות.

[ ] סמן, 'כמו _ של' דגימות עקביות.

[ ] ורסינינג ומדיניות הפחתה.

[ ] חוברות אינטרנט עם חתימות/קבלות, שידור חוזר ודדופ.

[ ] עקבות/מדדים/יומנים, SLO ורונות.

[ ] יומני תולעת, חתימות DSSE, פרוסות מרקל.

[ ] SDK, ארגז חול, סימולטורים, דגימות קוד וכיצד.

22) FAQ

למה 202 לניתוחים ארוכים?
על מנת לא להחזיק את החיבור ולספק מגש/קבלה אמין באמצעות webhook.

האם אתה צריך גם OpenAPI וגם ASYncAPI?
כן: סנכרון לפקודות/בקשות, אסינק לאירועים/משא ומתן מדיני.

איך להימנע משינויים?
חוק הוספה בלבד, פחת = = תצפית = הסרה, חוזה מבחן לקוח.

איפה לאחסן קבלות?
באזור תולעת עם חתימות; 'receit _ hash' מוחזר ללקוח ובדק בקשה.

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