Contract से शुरू करें

REST API documentation की दो audiences हैं: machine और human. Machine-readable contract paths, methods, parameters, schemas और responses बताता है; human docs intent, constraints और workflows समझाते हैं।

Happy path runnable होना चाहिए

Authentication, पूरा request और पूरा response दिखाएँ ताकि developer जल्दी पहला successful call कर सके। Examples valid और realistic हों।

Errors भी interface हैं

200 पर न रुकें। Authentication failures, validation errors, conflicts, limits और async states document करें और next action बताएँ।

Reference और guides अलग रखें

Reference “क्या मौजूद है?” बताता है; guide “goal कैसे पूरा करें?”। दोनों को link करें, एक ही भारी page में न मिलाएँ।

Examples executable रखें

जहाँ संभव हो JSON, schema और representative requests को CI में validate करें।

OpenAPI source है, पूरा experience नहीं

OpenAPI reference और validation के लिए अच्छा है, लेकिन business intent के लिए concepts, auth, limits और end-to-end scenarios भी चाहिए।

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

“REST API को सही तरह document कैसे करें” को एक पूर्ण 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 पहचान न सके।

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

  • Contract से शुरू करें. REST API documentation की दो audiences हैं: machine और human.
  • Happy path runnable होना चाहिए. Authentication, पूरा request और पूरा response दिखाएँ ताकि developer जल्दी पहला successful call कर सके। Examples valid और realistic हों।
  • Errors भी interface हैं. 200 पर न रुकें। Authentication failures, validation errors, conflicts, limits और async states document करें और next action बताएँ।
  • Reference और guides अलग रखें. Reference “क्या मौजूद है?” बताता है; guide “goal कैसे पूरा करें?”। दोनों को link करें, एक ही भारी page में न मिलाएँ।

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