Idempotency (אידמפוטנטיות) היא תכונה של פעולה שאפשר לבצע פעם אחת או עשר פעמים והתוצאה נשארת זהה. לחיצה על מתג "כבוי" היא אידמפוטנטית: גם אחרי חמש לחיצות האור כבוי. "שלח הודעה" היא לא: חמש בקשות הן חמש הודעות. ב-API, Idempotency היא הדרך להפוך את הפעולה השנייה לבטוחה.
למה זה נחוץ
הקוד שלכם שולח בקשה לשרת, והחיבור נופל לפני שהתשובה חזרה. ההודעה יצאה או לא? אין דרך לדעת. אם שולחים שוב, הלקוח עלול לקבל שתי הודעות ולשלם פעמיים; אם לא שולחים, אולי לא יקבל כלום. Idempotency Key פותר את הדילמה: שולחים שוב, והשרת מזהה שזו אותה בקשה.
איך Idempotency Key עובד
- הקוד שלכם מצרף לכל בקשת שליחה מזהה ייחודי משלכם, למשל מספר ההזמנה או UUID.
- השרת שומר את המזהה עם התוצאה של הבקשה הראשונה.
- בקשה חוזרת עם אותו מזהה לא מבצעת שליחה נוספת: השרת מחזיר את התוצאה המקורית.
המזהה צריך להיות ייחודי לפעולה, לא ללקוח: שתי הודעות שונות לאותו אדם הן שני מפתחות.
איך זה נראה ב-Sendy
ב-API של Sendy המפתח עובר ככותרת HTTP בשם Idempotency-Key על בקשת השליחה. שליחה חדשה מחזירה 202, ובקשה חוזרת עם אותו מפתח מחזירה 200 עם אותה הודעה, אותו מזהה ואותו חיוב, בלי הודעה שנייה ובלי קרדיט נוסף. אותו מפתח עם גוף בקשה שונה נדחה, כדי שטעות בקוד לא תתחפש לחזרה.