טכנולוגיה ותשתית * API Versioning

וריאציות של API

1) למה אתה צריך את זה

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

2) סיווג שינויים

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

SEMVER 'MAJOR מומלץ. מינורי. PATCH 'עבור חפצים (SDK/schemas), בעוד שמספר API ”חיצוני” ניתן לפשט (v1, v2).

3) מנוחה מודלים

1. לאורי:

”קבל/V1/תשלומים/”

מקצוענים: שקופים, נגישים, קלים לנתיב. חסרונות: שכפול של תיעוד, קשה יותר להתפתח בעדינות.

2. בכותרות (משא ומתן תוכן):

קבל: בקשה/וונד. חברה. תשלומים. v2 + json &pos

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

3. בכותרת מותאמת אישית:

'X-API-Version: 2' (Office Api-Version: 2025-09-01)

מקצוענים: רק על הסכר. חסרונות: אין סטנדרטיות, זהירות עם מטמון.

4. גרסה מבוססת תאריך:

טוב עבור פינטק/דיווח: ”חתכים” צפויים של שינוי (למשל. רבעון).

5. משאב/מודל ורסיונינג:

המלצה: עבור אינטגרציות חיצוניות - 'URI vN' + דחייה/כותרות שקיעה; עבור פנים - אתה יכול 'לקבל' או את הגרסא כותרת, אם השער והפלטפורמה תומכים בו.

4) GraphQL

העדפה - אין גרסאות גלובליות. אבולוציה באמצעות הוספת שדות/סוגים ופחת ("@ decreted (סיבה:... "")').
שבירת שינויים - רק בחלונות ”גדולים” (schema name space) עם מדריך הגירה.
צפו ב- ”n + 1” ואל תשנו את משמעות השדות הקיימים.

5) gRPC/Protobuf

מספרי שדה הם בלתי ניתנים לשינוי. סמן את השדות שנמחקו כ ”שמורים”.
הוסף שדות כאפשרות עם ברירת מחדל בטוחה.
השתמש בשבירת buf/מוך לבדיקת תאימות אוטומטית.
חבילות גרסה/מודולים: "תשלומי חבילה. v1, תשלומים. v2 '.

6) אפי אירוע (EDA)

ערכת האירוע היא אותו חוזה. שמרו אותו במרשם הסכמות (Avro/JSON-Schema/Protobuf).
נושאים וגרסאות: 'תשלומים. V1. מורשה, תשלומים. V2. מורשה '.
שבירת שינויים - סוג חדש של אירוע או נושא חדש.
אבולוציה מבטיחה: התאמה לאחור לצרכנים בתקופת ה-LTS.

7) מדיניות דיפריקציה ו ־ EOL

• הפחתה: תוויות בצ 'אנגלוג ובמפרט (OpenAPI/GraphQL SDL), כותרת
• 'דיכאון: נכון' וכאשר אפשרי 'שקיעה: Tue, 31 מאר 2026 00:00 GMT ".
• תקשורת: פורטל דוא "ל/שותף, הודעות באינטרנט, הערות שחרור.
• תנאים: מינור - 3-6 חודשים של תמיכה, מייג 'ור - 9-18 חודשים (תלוי בביקורתיות).
• חלונות זמן: תיקון במדיניות API Versioning.

8) ניתוב ושחרור

Gateway API (Kong/Apigee/Nginx/Enversoy): כללים על ידי קידומת '/v1/', על ידי כותרת או מדיאטייפ.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: לגלגל את הגרסה החדשה על 1-5% מהתנועה, להשוות מדדים ויומנים של שגיאות חוזה.
דגלים: הסתר התנהגות ללא שינוי בחוזה.
נדידת אפס-השבתה: עם MAJOR, לספק דו-כתיבה/לקרוא של סכימת הנתונים.

9) בדיקת חוזה ובקרת תאימות

OpenAPI DIFF (או swagger-diff) - בדוק כי MINOR/PATCH אינו שובר את הסכמות.
ציפוי ספקטרלי - בסגנון Metadata (גרסה, Deprection).
החוזים המונעים על ידי צרכנים מבטיחים שהספק לא ישבור לקוחות.
Buf שבירה pertobuf.
מודיע צריך ליפול בשינויים שבירה בלי להעלות מייג 'ור.

10) תיעוד ו ־ SDK

גרסה של המפרט: '/docs/api/v1/openapi. ג 'סון, '/docs/api/v2/'...
יצירת SDK על ידי גרסה (npm/maven/pipi) עם SemVer וchangelog.
סמן שיטות לא מדורגות ב ־ SDK עם/הערות מופרכות.

11) תצפית לפי גרסה

• RPS/latency/שגיאות לגרסה ('api _ version' label).
• מפות שימוש באנדפוינט: מי עוד נמצא על V1?
• התראות: ”> 10% 4xx עקב אי התאמת חוזה”, ”לקוחות ישנים> X% לאחר T-Date”.

12) מטמון וגרסאות

גרסת המעבר משפרת את יכולת הקיבול של CDN.

• 'Vary: קבל, X-API-גרסה ".
• אל תשנה את הסמנטיקה של התגובה בMINOR כדי לשבור מפתחות מטמון.

13) בטיחות

אין להצפין או לתפור את הגרסה לתוך JWT - הגרסה נקבעת על ידי הבקשה, לא האסימון.
אל תחשוף מספרי הרכבה פנימיים. השתמש ב ”v1/v2” עבור הודעות חיצוניות.
בסרן, סקירת אימות, הגבלות, מיסוך מח "ש.

14) נדודים ועוזרים אוטומטיים

פרסמו את ”Migration Guide v1 # v2”: טבלת מיפוי שדה, בקשות/תגובות לדוגמה, מקרי קצה.
אנחנו מציעים ספינים ללקוחות (CLI) שמדגישים שדות מיושנים.
לשותפים גדולים - ארגז חול עם שתי גרסאות ומידע מבחן.

15) אנטי דפוסים

”נצח v1”: היעדר מועדים ומדי שימוש.
שינויי שבירה חבויים ב - MINOR/PATCH.
"גרסה במחרוזת שאילתה" ("? V = 2 ') - שובר מטמון וקריאה.
"נקודה אחת היא מאה ערכי דגל: קשה לבחון/לתעד.

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

1. מודל נבחר (URI/קבל/כותרת) עבור לקוחות חיצוניים ופנימיים.
2. SemVer למפרט ו-SDK, בדיקת שבירה אוטומטית במודיעה.
3. מדיניות ביטול/שקיעה ותבנית תקשורת.
4. ניתוב שער + קנריות, לוחות מחוונים לפי גרסה.
5. בדיקות CDC/Contract לאינטגרציה קריטית (תשלומים, KYC, דיווח).
6. המסמכים/מדריך הנדידה של SDK מתפרסמים במקביל ליציאה לאור.
7. תוכנית עם תאריכים ואחריות.

17) דוגמאות

17. 1 מנוחה (אורים + כותרות)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 משא ומתן תוכן

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (Depriction שדה)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 GRPC (פרוטובוף)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 מודל אירועים

• "וואלט. V1. איזון. עדכון &posted
• "וואלט. V2. איזון. השתנה (אירוע חדש עם סכימה מורחבת)

מזימות מאוחסנות ב-Registry, המפיק אינו מפרסם אירועים עם מזימה המפרה תאימות.

18) הקשר iGaming/fintech (פרקטיקה)

תשלומים: קלט V2 עבור PSPs חדשים שבו 'סטטוס '/' ירידה _ סיבה' מורחב; בשער, מיפוי v1 כפול v2 לדיווח.
KYC: MINOR מוסיף שדה ”pep _ screening”, לקוחות מתעלמים מ v1, v2 - דורש.
משחקים אחראיים/גבולות: MAJOR משנה את מודל הגבולות (יומי/שבועי). יצוא כפול לדיווח לפני EOL V1.
דיווח לרגולטורים: גרסאות-תאריכים קבועים: ”דיווח 2025-01”.

19) מיני-מדיניות (דוגמה לוויקי)

מודל: עבור API חיצוני - ”URI/vN/”; לקבלת פנים - "קבל:... VN + json 'או' X-API-Version: N '.
SEMVER: מפרט ו-SDKs מתפרסמים כ-N. מינורי. תיקון '. מייג 'ור דורשת RFC/ADR.
תאימות: MINOR/PATCH - אין שינויים שבירה. שובר כפול רק דרך מייג 'ור.
ביטול/EOL: הודעה בת 90 יום; תאריך שקיעה בכותרות; סניף LTS ללקוחות קריטיים.
בקרה: OpenAPI diff/buf breaking in CI, CDC עבור אינטגרציית מפתח.
תצפית: metrics/logs עם התווית api _ version.
משחרר: קנרית 5% -24h, ואז בשלבים עד 100% עם מדדים ירוקים.

תוצאות

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