HTTP API एरर हैंडलिंग की कठिनाइयाँ और RFC7807

HTTP API विकसित करते समय एरर हैंडलिंग अक्सर एक झंझटभरा हिस्सा होती है। जैसे-जैसे API की संख्या बढ़ती है और internal logic जटिल होती जाती है, तीन पहलुओं में कठिनाइयाँ सामने आती हैं.

• उचित एरर कोड लौटाना: कम अनुभव वाले डेवलपर के लिए जटिल logic में लगातार एकसमान HTTP status code का उपयोग करना कठिन होता है।
• बहुत अधिक result log लिखना: एरर होने पर हर संभावित exit point पर log रिकॉर्ड करना code की मात्रा बढ़ाता है और management को जटिल बनाता है।
• स्पष्ट एरर संदेश भेजना: client को केवल एरर संदेश भेज देने से एरर को स्पष्ट रूप से समझना और संभालना मुश्किल होता है।

उचित एरर कोड लौटाने में सुधार

एरर कोड के उपयोग में consistency की समस्या हल करने के लिए StatusCode और Message को शामिल करने वाला HttpError interface या struct लागू करने का सुझाव दिया गया है।

• समाधान:
  • HttpError type परिभाषित करना: HTTP status code और message को encapsulate करना।
  • helper function प्रदान करना: httperror.BadRequest("wrong format") की तरह विशेष एरर कोड लौटाने वाले helper function का उपयोग करके एरर object आसानी से बनाना।
• फायदे:
  • IDE के auto-completion feature का उपयोग करके सुविधाजनक और स्थिर तरीके से एरर code और message दर्ज करना।
  • हाथ से numeric code डालने की तुलना में गलती की संभावना कम होना।
  • पहले से तैयार design document को बार-बार देखने की झंझट कम होना।

log लेखन का केंद्रीकरण

दोहराव वाले log लेखन को कम करने और एरर हैंडलिंग logic को एक जगह प्रबंधित करने के लिए HTTP handler को wrap करने की विधि प्रस्तुत की गई है।

• समाधान:
  • custom router(chiwrap.Router) लागू करना: chi.Router जैसे मौजूदा router को अंदर शामिल करके उसमें एरर हैंडलिंग logic जोड़ना।
  • handler wrapping: custom router के Get जैसे method HandlerFunc को लेकर उसे अंदर चलाते हैं, और एरर होने पर उसे केंद्रीय processing logic तक पहुँचाते हैं।
  • एरर callback function: NewRouter बनाते समय errCallback function लेना, ताकि एरर होने पर वही callback कॉल हो और वहीं से केंद्रीय log लेखन या अतिरिक्त processing की जा सके।
• फायदे:
  • API logic में एरर होने पर अपने-आप उचित एरर code और message response में लौटते हैं।
  • service के अनुसार उपयुक्त log लिखने के लिए callback function register किया जा सकता है, जिससे log management आसान होता है।
  • code duplication कम होती है और maintainability बेहतर होती है।

स्पष्ट एरर संदेश भेजना (RFC7807 का उपयोग)

client एरर को अधिक स्पष्ट रूप से समझ सके और उसे संभाल सके, इसके लिए RFC7807 standard का उपयोग कर structured एरर संदेश भेजने का तरीका सुझाया गया है।

• RFC7807 के मुख्य तत्व:
  • type: एरर प्रकार की पहचान करने वाला URI (उदाहरण: https://example.com/errors/validation)।
  • title: एरर के लिए छोटा एक-पंक्ति विवरण।
  • status: HTTP status code के समान।
  • detail: इंसानों द्वारा पढ़ा जा सकने वाला विस्तृत एरर विवरण।
  • instance: वह विशिष्ट URI जहाँ एरर हुआ (उदाहरण: /api/users/abc)।
  • extensions: अतिरिक्त जानकारी रखने वाला JSON object (उदाहरण: invalid_field, expected_format)।
• कार्यान्वयन:

  • RFC7807Error struct बनाना और उसमें मुख्य तत्व शामिल करना।

  • method chaining pattern (WithType(), WithInstance(), WithExtension()) के जरिए structured एरर object आसानी से बनाना।

  • ToHttpError() method के जरिए RFC7807Error को HttpError में बदलना, ताकि इसे centralized router के साथ जोड़ा जा सके।

  • client एरर के प्रकार, कारण और होने की जगह को स्पष्ट रूप से समझ सकता है।

  • API response की consistency और उपयोगिता बढ़ती है, जिससे client development की efficiency बेहतर होती है।

[aer0700]

अच्छा लेख है, धन्यवाद

[beoks]

अच्छा लेख, धन्यवाद!
जानकारी के लिए, Spring में org.springframework.http.ProblemDetail के लिए implementation spring-web लाइब्रेरी में मौजूद है!

[honglu]

अच्छी परिचयात्मक पोस्ट के लिए धन्यवाद!
देखा तो पता चला कि इसे RFC 9457 से बदल दिया गया है।

https://datatracker.ietf.org/doc/html/rfc9457
(पुराना 7807 दस्तावेज़: https://datatracker.ietf.org/doc/html/rfc7807)

[findnamo]

RFC 7807 और RFC 9457 के बीच मुख्य अंतर

• problem type management: 7807 में केवल custom URI का उपयोग संभव है, 9457 में IANA shared registry पेश किया गया है
• multiple error handling: 7807 में HTTP 207 status code के उपयोग की सिफारिश है, 9457 में एक single problem type के भीतर errors array का उपयोग करके संबंधित errors को group किया जाता है
• extension fields: 7807 में arbitrary fields जोड़े जा सकते हैं, 9457 में problem type के अनुसार expected fields को स्पष्ट रूप से associate किया जाता है
• security recommendations: 7807 में शामिल नहीं, 9457 में security vulnerabilities को रोकने के लिए स्पष्ट guidelines जोड़ी गई हैं
• JSON pointer: 7807 में support नहीं, 9457 में pointer field का आधिकारिक support है

जुलाई 2023 के बाद शुरू होने वाले नए projects में RFC 9457 लागू करने की सिफारिश की जाती है

[honglu]

type फ़ील्ड को dereference किया जा सकने वाले URI के रूप में सेट करना सुझाया गया लगता है।

आंतरिक सेवाओं में इसे Swagger-ui दस्तावेज़ लिंक से बदलना भी ठीक लग रहा है।