मी स्पष्ट API दस्तऐवजीकरण लिहीन जे तुमचे डेव्हलपर्स पहिल्या दिवसापासून फॉलो करू शकतील

बहुतेक API दस्तऐवज का अयशस्वी होतात

ते एंडपॉइंट्सचे वर्णन करतात आणि लोकांना प्रत्यक्षात थांबवणारे भाग वगळतात: प्रमाणीकरण कसे करावे, वास्तविक विनंती कशी दिसते, त्रुटीचा अर्थ काय आहे आणि त्यावर काय करावे. त्यानंतर वाचक समर्थन तिकीट उघडतो, जी दस्तऐवजीकरण काढून टाकण्यासाठी अस्तित्वात असलेली किंमत आहे.

मी ते कसे लिहितो

स्मृतीतून नाही, तर स्त्रोतावरून. मी मार्ग, प्रमाणीकरण स्तर आणि त्रुटी हँडलर वाचतो, त्यानंतर वास्तविक क्रेडेन्शियल्ससह स्वतः API ला कॉल करतो. दस्तऐवजातील प्रत्येक उदाहरण ही मी केलेली विनंती आणि मला मिळालेला प्रतिसाद आहे — कोणतेही तयार केलेले पेलोड नाहीत, एंडपॉइंट कधीही परत न करणारे स्टेटस कोड नाहीत.

दस्तऐवजात काय आहे

• प्रमाणीकरण: टोकन मिळवणे, ते रीफ्रेश करणे आणि सत्राच्या मध्यभागी ते कालबाह्य झाल्यास काय होते.
• पॅरामीटर्ससह प्रत्येक एंडपॉइंट, एक पूर्ण उदाहरण विनंती आणि वास्तविक प्रतिसाद आकार.
• एक त्रुटी संदर्भ जो प्रत्येक त्रुटी कोडला कारण आणि निराकरणाशी जोडतो, केवळ संदेश पुन्हा न सांगता.
• एक प्रारंभ मार्ग जो नवीन डेव्हलपरला शून्य ते यशस्वी कॉलपर्यंत दहा मिनिटांपेक्षा कमी वेळेत घेऊन जातो.
• जेथे ते प्रत्यक्षात लागू होतात तेथे दर मर्यादा, पृष्ठसंख्या, वेबहुक्स आणि आयडेम्पोटेंसी स्पष्ट केली आहे.

स्वरूप

तुमच्या रेपॉजिटरीमध्ये मार्कडाउन, ओपनएपीआय किंवा डॉक्स साइटसाठी संरचित — जे तुम्ही प्रत्यक्षात राखाल. तुमच्या वापरकर्त्यांनी विचारलेल्या भाषांमध्ये कोड नमुने, ते चालवून सत्यापित केलेले. तुम्हाला हवे असल्यास पोस्टमन किंवा तत्सम कलेक्शन समाविष्ट.

मला काय हवे आहे

रेपॉजिटरी ॲक्सेस किंवा ओपनएपीआय फाइल, चाचणी वातावरणासाठी एक कार्यरत क्रेडेन्शियल आणि तुमच्या समर्थन टीमला उत्तरे देऊन कंटाळलेले कोणतेही प्रश्न. ते प्रश्न रूपरेषा आहेत.

समाविष्ट नाही

मार्केटिंग कॉपी. हे सॉफ्टवेअर काय करते, ते अचूकपणे दस्तऐवज करते; लँडिंग पृष्ठ एक वेगळी कला आहे.

टर्नअराउंड आणि संवाद

पहिला पूर्ण मसुदा सहसा एका आठवड्यात येतो आणि तुम्ही तुमच्या स्वतःच्या समर्थन टीमने उत्तरे दिलेल्या प्रश्नांविरुद्ध त्याचे पुनरावलोकन करता. मी पॉलिश केलेले आणि चुकीचे काहीतरी वितरित करण्याऐवजी, एज केसेस माहित असलेल्या अभियंत्याकडून लवकर दुरुस्त केले जाणे पसंत करेन. अंतिम दस्तऐवजातील प्रत्येक उदाहरण तुमच्या API विरुद्ध कार्यान्वित केले गेले आहे, त्यामुळे त्यात काहीही महत्त्वाकांक्षी नाही.