ניסיונות חוזרים בטוחים

איך זה עובד

שלחו כותרת Idempotency-Key — 1 עד 100 תווי ASCII מודפסים, UUID מתאים בדיוק — והשתמשו באותו ערך בכל ניסיון חוזר של אותו שינוי. נקודות קצה שתומכות בזה מסומנות בתג Idempotency-Key במדריך העיון.

curl -s -X POST https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321/transactions \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c6a2e-8d4b-4c1e-9a7f-2b3c4d5e6f70" \
  -d '{"type":"add","amount":100,"reason":"Tournament prize"}'

• תשובות מוצלחות נשמרות 24 שעות לכל מפתח API. ניסיון חוזר עם אותו מפתח ואותה בקשה מחזיר את התשובה המקורית (אותו סטטוס ואותו גוף, ועוד הכותרת Idempotent-Replayed: true) בלי לשנות שום דבר שוב.
• אותו מפתח עם גוף, חבר/ה או נתיב אחרים נכשל עם 422 IDEMPOTENCY_KEY_REUSED.
• בקשות שנכשלו (4xx ו-5xx) לא נשמרות, כך שאפשר לתקן את הבעיה ולנסות שוב עם אותו מפתח.
• גם שתי בקשות עם אותו מפתח באותו רגע בטוחות: השנייה מחכה לראשונה ואז מקבלת את התשובה השמורה שלה.
• בלי הכותרת, בקשה חוזרת היא שינוי חדש.

HTTP/1.1 201 Created
Idempotent-Replayed: true

{ "transactionId": 98765, "balance": 1350, ... }

HTTP/1.1 422 Unprocessable Entity

{ "error": "IDEMPOTENCY_KEY_REUSED", "message": "This Idempotency-Key was already used with a different request" }

בפועל

1. צרו מפתח פעם אחת לכל פעולה לוגית (למשל לכל תשלום פרס בטורניר), לפני הניסיון הראשון.
2. שמרו אותו יחד עם הפעולה במסד הנתונים שלכם אם ניסיון חוזר עלול לקרות אחרי הפעלה מחדש.
3. בפסק זמן, בשגיאת רשת, ב-429, ב-500 או ב-503, שלחו בדיוק את אותה בקשה עם אותו מפתח.
4. לפעולה הבאה, השונה, השתמשו במפתח חדש.