Idempotency-Key: PDF कार्यों के लिए सुरक्षित पुनः प्रयास
POST /api/v1/ के अंतर्गत Idempotency-Key भेजें। PDF123 सफल जवाब 24 घंटे प्रक्रिया मेमोरी में कैश करता है; Idempotency-Replayed: true दोबारा चलाने से बचाता है।

मल्टीपार्ट PDF अपलोड में नेटवर्क टाइमआउट और क्लाइंट के पुनः प्रयास आम हैं। इडेम्पोटेंसी कुंजी के बिना दूसरा POST वही मर्ज, OCR या संपीड़न शुरू से दोबारा चलाता है, जिससे अपलोड और प्रसंस्करण समय दोहरा जाता है। Idempotency-Key के साथ PDF123 पहली सफल प्रतिक्रिया दोबारा भेज सकता है।
मिडलवेयर क्या करता है
pdfx-server का सर्वर मिडलवेयर केवल बदलाव करने वाली कॉलों पर लागू होता है: /api/v1/ के नीचे के रास्तों पर POST (/api/v1/pipeline सहित)। GET और बाक़ी विधियाँ बिना बदलाव गुज़र जाती हैं। अगर अनुरोध में Idempotency-Key शीर्षलेख न हो (या छाँटने के बाद खाली हो), तो प्रचालन सामान्य रूप से चलता है, कोई कैश खोज नहीं।
जब शीर्षलेख मौजूद हो:
- भंडार प्रविष्टि को प्रिंसिपल + कुंजी से कुंजीबद्ध करता है। प्रिंसिपल
X-API-KEYसे लिया जाता है (key:…के रूप में), वरनाAuthorizationसे (auth:…), वरना शब्दशःanon। इन दोनों मानों को मैप-कुंजी में हैश (SHA-256) कर लिया जाता है; अनुरोध-निकाय कुंजी का हिस्सा नहीं है। - 24 घंटे के भीतर कैश हिट पर मिडलवेयर संग्रहीत स्थिति, content type, content disposition और निकाय लौटाता है, और
Idempotency-Replayed: trueसेट करता है। - मिस पर अनुरोध आगे बढ़ता है। केवल सफल प्रतिक्रियाएँ बफ़र होकर संग्रहित होती हैं (असफल प्रतिक्रियाएँ पुनरावृत्ति के लिए कैश नहीं होतीं)।
- प्रतिक्रिया-निकाय 100 MiB तक बफ़र होते हैं ताकि पुनरावृत्ति फ़ाइल के बाइट्स दोबारा भेज सके। जो निकाय बफ़र न हो सके, वह चुपचाप कैश नहीं छोड़ता: वह अनुरोध HTTP 500 लौटाता है, यानी सीमा से बड़ा जवाब बिना कैश हुए आगे निकलने के बजाय फेल होता है।
असफल कार्य उसी कुंजी के साथ दोबारा चलाना सुरक्षित है: विफलताएँ संग्रहित नहीं होतीं, इसलिए अगली कोशिश सफल होकर कैश किया नतीजा बन सकती है। किसी दूसरी फ़ाइल या मापदंडों के लिए कुंजी दोबारा न इस्तेमाल करें; कैश निकाय को हैश नहीं करता, सिर्फ़ प्रिंसिपल और कुंजी को। जो दो कॉलर न API कुंजी साझा करते हैं न Authorization, वे संयोग से टकरा नहीं सकते—अनाम कॉलर anon प्रिंसिपल साझा करते हैं, इसलिए उन्हें अलग-अलग कुंजी चुननी चाहिए।
इसे कैसे भेजें
हर तार्किक कार्य के लिए एक स्थिर अपारदर्शी स्ट्रिंग चुनें (UUID ठीक है):
curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-F "[email protected]"
अनाम और API कुंजी वाले कॉलर दोनों चलते हैं। जो पाइपलाइन पहले वॉटरमार्क फिर संपीड़न करती हैं, उन्हें भी हर उस HTTP अनुरोध पर एक कुंजी भेजनी चाहिए जिसे आप डिडुप्लिकेट करना चाहते हैं—अलग-अलग POST करें तो हर चरण पर, या एक /api/v1/pipeline कॉल के लिए एक कुंजी।
टूल पेजों पर ब्राउज़र से किए एक-बारगी कामों (Compress, OCR, …) के लिए आपको कुंजी गढ़नी नहीं पड़ती; यह शीर्षलेख उन क्लाइंट के लिए मायने रखता है जो पुनः प्रयास करते हैं। /skills/pdf123.md पर प्रकाशित स्किल इसी कारण पाइपलाइन उदाहरण में Idempotency-Key दिखाती है।
काम करने वाले क्लाइंट पैटर्न
- पहले POST से पहले कुंजी बनाएँ; उसी तार्किक कार्य के टाइमआउट पुनः प्रयासों में उसे दोबारा इस्तेमाल करें।
- सफलता पर
Idempotency-Replayed: trueदेखें, अगर यह जानना हो कि यह प्रतिक्रिया कैश से आई या प्रचालन दोबारा चला। - फ़ाइल, प्रचालन या मापदंड बदलने पर कुंजी बदलें, भले प्रिंसिपल वही रहे।
/api/v1/pipelineके लिए एक कुंजी पूरे पाइपलाइन POST को कवर करती है, हर भीतरी चरण को नहीं।
पुनरावृत्ति क्या नहीं है
पुनरावृत्ति टिकाऊ कार्य-कतार नहीं है। भंडार प्रक्रिया-स्थानीय (HashMap, mutex के पीछे) है, 24 घंटे TTL के साथ। समय-सीमा बीतने पर, या प्रक्रिया-पुनःआरंभ से इन-मेमोरी मैप गिर जाने पर, वही कुंजी प्रचालन दोबारा चलाती है। बहु-इंस्टेंस तैनातियाँ वह मैप साझा नहीं करतीं जब तक आप आगे साझा भंडार न लगाएँ—आज का मिडलवेयर प्रति-प्रक्रिया है।
Idempotency-Replayed: true को इस बात का प्रमाण मानें कि यह प्रतिक्रिया कैश से आई, स्थायी बहीखाता नहीं। इसका अर्थ यह नहीं कि PDF दोबारा प्रसंस्कृत हुई, और यह TTL नहीं बढ़ाता।
ज़्यादा ब्योरा: Developers और AI एजेंट के लिए बनाया गया। Compress जैसे टूल पेज बिना कुंजी गढ़े एक-बारगी ब्राउज़र कामों के लिए उपलब्ध रहते हैं।