Valid होना बस शुरुआत है

Schema से निकला example syntactically correct हो सकता है लेकिन कुछ सिखाए नहीं। string, 123 और foo validator pass कर लेते हैं, पर domain meaning छिपा देते हैं। अच्छा example बताता है कि request क्यों है और success के बाद क्या किया जा सकता है।

Realistic identifiers इस्तेमाल करें, लेकिन real secrets या personal data नहीं।

छोटी narrative बनाएं

Real task जैसी sequence दें: resource create करें, retrieve करें, update करें, फिर failure या cleanup दिखाएँ। IDs reuse करें ताकि relationships दिखें।

Reference pages पर हर endpoint के नीचे बड़ा tutorial copy करने के बजाय relevant workflow link करें।

महत्वपूर्ण response दिखाएँ

Request पर न रुकें। Status, important headers और body दिखाएँ। Non-obvious fields explain करें। Async operation में client completion कैसे जानता है, यह भी दिखाएँ।

Error examples उतने ही महत्वपूर्ण हैं। Realistic validation error अक्सर एक और happy path से अधिक सिखाता है।

Examples executable रखें

जहाँ संभव हो CI में requests run करें या payload contract से validate करें। Samples को files या generated snippets के रूप में रखें, कई pages में manual copies के रूप में नहीं।

Adaptation के लिए optimize करें

बताइए कि reader कौन-से values बदले और कौन-से assumptions कायम रहें। Example का goal transferable mental model है।

अगर example अगली request design करना आसान नहीं बनाता, तो वह शायद decoration है।

व्यावहारिक उदाहरण

“API examples workflow सिखाएँ, reference page सजाएँ नहीं” को एक पूर्ण developer task में बदलें। कोई काल्पनिक लेकिन वास्तविक-सा resource चुनें—report, device या order—और authentication से सफल result तक का सबसे छोटा रास्ता लिखें। Request, महत्वपूर्ण response fields, एक सामान्य failure और उसके बाद की कार्रवाई शामिल करें।

मान लें कि इसी example से client बनाया जा रहा है:

  • developer किन values को बदलेगा;
  • server कौन-सी IDs लौटाता है और वे आगे कहाँ काम आती हैं;
  • कौन-सा status या field सफलता बताता है;
  • credentials, input या rate limit विफल होने पर क्या करना है।

API documentation तब उपयोगी है जब developer interaction का अनुमान लगा सके, केवल endpoint names पहचान न सके।

त्वरित संपादकीय जाँच

  • Valid होना बस शुरुआत है. Schema से निकला example syntactically correct हो सकता है लेकिन कुछ सिखाए नहीं। string, 123 और foo validator pass कर लेते हैं, पर domain meaning छिपा देते हैं। अच्छा example बताता है कि request क्यों है और success के बाद क्या किया जा सकता है…
  • छोटी narrative बनाएं. Real task जैसी sequence दें: resource create करें, retrieve करें, update करें, फिर failure या cleanup दिखाएँ। IDs reuse करें ताकि relationships दिखें।
  • महत्वपूर्ण response दिखाएँ. Request पर न रुकें। Status, important headers और body दिखाएँ। Non-obvious fields explain करें। Async operation में client completion कैसे जानता है, यह भी दिखाएँ।
  • Examples executable रखें. जहाँ संभव हो CI में requests run करें या payload contract से validate करें। Samples को files या generated snippets के रूप में रखें, कई pages में manual copies के रूप में नहीं।

संबंधित सामग्री