المفاهيم

منع التكرار

إعادة المحاولة لا تُنشئ مرتين أبدًا: كل طلب POST منشئ يحمل Idempotency-Key.

يتطلب كل طلب POST ينشئ سجلًا ترويسة Idempotency-Key: من 1 إلى 100 حرف ASCII ظاهر، مثل UUID، جديدة لكل طلب. ويضع المرجع علامة على تلك العمليات.

إن أُرسلت مرة أخرى بالطريقة والمسار والجسم أنفسهم خلال 24 ساعة، تُعاد الاستجابة الأولى مع Idempotent-Replayed: true ولا يُنفَّذ شيء مرتين.
وإن أُرسلت مع طلب مختلف تُرفض 422 IDEMPOTENCY_KEY_REUSED.
إن كانت مفقودة أو غير صالحة: 400 IDEMPOTENCY_KEY_REQUIRED أو IDEMPOTENCY_KEY_INVALID.
يُنفَّذ الإنشاء في معاملة واحدة مع سجل استجابته: فالرفض لا يترك أثرًا، ويمكن استخدام المفتاح نفسه مجددًا للطلب المصحّح.

http

HTTP/1.1 201 Created
Idempotent-Replayed: true
{ …the first answer, unchanged… }

إعادة المحاولة بالشكل الصحيح

أنشئ المفتاح عند بناء الطلب، واحفظه معه، وأعد استخدامه في كل إعادة محاولة لذلك الطلب — بعد انتهاء المهلة أو انقطاع الاتصال أو استجابة 5xx. الطلب الجديد وحده يأخذ مفتاحًا جديدًا. والإجراءات على المستندات القائمة لا تحتاج مفتاحًا: فهي آمنة للتكرار بذاتها (الاصطلاحات).

يحتفظ مسار POST /bills القديم بطريقته الخاصة في منع التكرار، عبر رقم مرجع المورّد، والترويسة فيه اختيارية.