HTTP APIs के लिए संरचित त्रुटि संदेश

Nicolas Fränkel

Nicolas Fränkel

November 2, 2022

Technology

जब से मैंने Apache APISIX प्रोजेक्ट पर काम करना शुरू किया है, मैं REST RESTful HTTP APIs के बारे में अपने ज्ञान और समझ को बेहतर बनाने की कोशिश कर रहा हूँ। इसके लिए, मैं निम्नलिखित स्रोतों को पढ़ और देख रहा हूँ:

  • किताबें। इस समय, मैं API Design Patterns को पूरा कर रहा हूँ। जल्द ही एक समीक्षा की उम्मीद है।
  • YouTube। मैं ErikWilde' चैनल की सिफारिश करूंगा। हालांकि कुछ वीडियो दूसरों से बेहतर हैं, वे सभी APIs पर केंद्रित हैं।
  • IETF RFCs। अधिकांश RFCs APIs के बारे में नहीं हैं, लेकिन एक दोस्ताना व्यक्ति ने उनकी सूची संकलित की है।

आज, मैं "Problem Details for HTTP APIs" RFC, अर्थात, RFC 7807 का परिचय देना चाहूंगा।

समस्या(एं)

REST सिद्धांत संचार के लिए HTTP स्थिति का उपयोग करने का निर्देश देते हैं। त्रुटियों के लिए, HTTP दो श्रेणियों को परिभाषित करता है: क्लाइंट त्रुटियाँ, 4xx, और सर्वर त्रुटियाँ, 5xx।

कल्पना कीजिए कि एक बैंकिंग API है जो आपको ट्रांसफर करने की अनुमति देता है। यदि आप अपने खाते में अधिक धनराशि ट्रांसफर करने का प्रयास करते हैं, तो यह विफल हो जाना चाहिए। कुछ HTTP स्थिति कोड फिट हो सकते हैं:

  • 400 Bad Request: सर्वर अनुरोध को संसाधित नहीं कर सकता या नहीं करेगा क्योंकि यह क्लाइंट त्रुटि के रूप में माना जाता है।
  • 402 Payment Required: अनुरोध को तब तक संसाधित नहीं किया जा सकता जब तक क्लाइंट भुगतान नहीं करता। हालांकि, कोई मानक उपयोग सम्मेलन मौजूद नहीं है, और विभिन्न संस्थाएं इसे अन्य संदर्भों में उपयोग करती हैं।
  • 409 Conflict: अनुरोध लक्ष्य संसाधन की वर्तमान स्थिति के साथ संघर्ष करता है।

यहाँ पहली समस्या है: HTTP स्थिति कोड ब्राउज़र के माध्यम से मानव-से-मशीन इंटरैक्शन के लिए निर्दिष्ट किए गए थे, APIs के माध्यम से मशीन-से-मशीन इंटरैक्शन के लिए नहीं। इसलिए, उपयोग केस के साथ एक-से-एक मैप करने वाले स्थिति कोड का चयन करना शायद ही कभी सीधा होता है। रिकॉर्ड के लिए, मार्टिन फाउलर हमारे मामले में 409 को पसंद करते हैं।

स्थिति कोड जो भी हो, दूसरी समस्या त्रुटि पेलोड या, अधिक सटीक रूप से, इसकी संरचना से संबंधित है। यदि क्लाइंट और API प्रदाता को एक ही संगठन द्वारा प्रबंधित किया जाता है, तो संरचना महत्वपूर्ण नहीं है। यहां तक कि यदि उनमें से प्रत्येक को एक समर्पित टीम द्वारा विकसित किया जाता है, तो वे संरेखित हो सकते हैं। उदाहरण के लिए, एक मोबाइल ऐप की कल्पना कीजिए जो अपने स्वयं के API को कॉल करता है।

हालांकि, जब एक टीम तीसरे पक्ष के API का उपयोग करने का निर्णय लेती है, तो समस्याएं उत्पन्न होती हैं। इस मामले में प्रतिक्रिया संरचना का चयन महत्वपूर्ण है क्योंकि इसे अब एक अनुबंध का हिस्सा माना जाता है: प्रदाता द्वारा किसी भी परिवर्तन से क्लाइंट टूट सकते हैं। इससे भी बदतर, संरचना प्रदाता से प्रदाता तक अलग होने की संभावना है।

इसलिए, एक मानकीकृत त्रुटि रिपोर्टिंग संरचना:

  • प्रदाताओं के बीच एकरूपता प्रदान करती है
  • API स्थिरता को बढ़ाती है

RFC 7807

RFC 7807 का उद्देश्य एक मानकीकृत त्रुटि संरचना प्रदान करके समस्या को हल करना है।

संरचना निम्नलिखित है:

संरचना

RFC फ़ील्ड्स का वर्णन करता है:

  • "type" (string) - एक URI संदर्भ [RFC3986] जो समस्या प्रकार की पहचान करता है। यह विशिष्टता प्रोत्साहित करती है कि, जब डीरेफरेंस किया जाता है, तो यह समस्या प्रकार के लिए मानव-पठनीय दस्तावेज़ीकरण प्रदान करे (जैसे, HTML [W3C.REC-html5-20141028] का उपयोग करके)। जब यह सदस्य मौजूद नहीं होता है, तो इसका मान "about:blank" माना जाता है।
  • "title" (string) - समस्या प्रकार का एक संक्षिप्त, मानव-पठनीय सारांश। इसे समस्या के प्रत्येक घटना में बदलना नहीं चाहिए, सिवाय स्थानीयकरण के उद्देश्यों के (जैसे, प्रोएक्टिव कंटेंट नेगोशिएशन का उपयोग करके; देखें [RFC7231, Section 3.4])।
  • "status" (number) - ([RFC7231], Section 6) मूल सर्वर द्वारा इस समस्या के घटना के लिए उत्पन्न किया गया।
  • "detail" (string) - इस समस्या के घटना के लिए विशिष्ट मानव-पठनीय व्याख्या।
  • "instance" (string) - एक URI संदर्भ जो समस्या के विशिष्ट घटना की पहचान करता है। यह डीरेफरेंस करने पर और जानकारी प्रदान कर सकता है या नहीं भी कर सकता है।

-- Problem Details Object के सदस्य

RFC बैंकिंग ट्रांसफर करने के लिए पर्याप्त धनराशि नहीं होने पर निम्नलिखित नमूना प्रदान करता है।

RFC उदाहरण

एक उदाहरण

मैं अपने मौजूदा डेमो में से एक का उदाहरण दूंगा। डेमो आपके APIs को विकसित करने की प्रक्रिया को आसान बनाने के लिए कई चरणों को उजागर करता है।

चरण 6 में, मैं चाहता हूँ कि उपयोगकर्ता पंजीकरण करें, इसलिए यदि वे प्रमाणित नहीं हैं, तो मैं एक समय विंडो में कॉल की संख्या को सीमित करता हूँ। मैंने इसके लिए एक समर्पित Apache APISIX प्लगइन बनाया है। कॉल की संख्या सीमा तक पहुंचने के बाद, यह लौटाता है:

HTTP/1.1 429 Too Many Requests
Date: Fri, 28 Oct 2022 11:56:11 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.15.0

{"error_msg":"Please register at https:\/\/apisix.org\/register to get your API token and enjoy unlimited calls"}

आइए संदेश को RFC 7807 के अनुसार संरचित करें।

RFC 7807 नियम

निष्कर्ष

RFC 7807 न केवल क्लाइंट डेवलपर्स की मदद करता है। यह API इम्प्लीमेंटर्स के लिए भी एक बड़ी मदद है क्योंकि यह हर प्रोजेक्ट पर पहिया को फिर से आविष्कार करने से बचने के लिए त्वरित दिशानिर्देश प्रदान करता है।

आगे बढ़ें:

मूल रूप से A Java Geek पर 30 अक्टूबर 2022 को प्रकाशित

Tags:
Codec