मैं स्पष्ट एपीआई दस्तावेज़ लिखूँगा जिसका आपके डेवलपर पहले दिन से पालन कर सकते हैं

अधिकांश API दस्तावेज़ क्यों विफल होते हैं

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

मैं इसे कैसे लिखता हूँ

स्रोत से, स्मृति से नहीं। मैं मार्गों, सत्यापन परत और त्रुटि हैंडलर को पढ़ता हूं, फिर वास्तविक क्रेडेंशियल के साथ API को स्वयं कॉल करता हूं। दस्तावेज़ीकरण में प्रत्येक उदाहरण एक अनुरोध है जो मैंने किया था और एक प्रतिक्रिया जो मुझे मिली थी - कोई आविष्कारित पेलोड नहीं, कोई स्थिति कोड नहीं जो एंडपॉइंट कभी वापस नहीं करता है।

दस्तावेज़ीकरण में क्या शामिल है

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

प्रारूप

आपकी रिपॉजिटरी में मार्कडाउन, OpenAPI या एक डॉक्स साइट के लिए संरचित - जिसे आप वास्तव में बनाए रखेंगे। आपकी उपयोगकर्ता जिन भाषाओं के बारे में पूछते हैं, उनमें कोड नमूने, उन्हें चलाकर सत्यापित किए गए। यदि आप चाहते हैं तो पोस्टमैन या समान संग्रह शामिल है।

मुझे क्या चाहिए

रिपॉजिटरी एक्सेस या OpenAPI फ़ाइल, एक परीक्षण वातावरण के लिए एक कार्यशील क्रेडेंशियल, और कोई भी प्रश्न जिसका आपकी सहायता टीम जवाब देते-देते थक गई है। वे प्रश्न रूपरेखा हैं।

शामिल नहीं

विपणन प्रतिलिपि। यह दस्तावेज़ बताता है कि सॉफ़्टवेयर क्या करता है, ठीक-ठीक; लैंडिंग पृष्ठ एक अलग शिल्प है।

टर्नअराउंड और संचार

एक पहला पूर्ण मसौदा आमतौर पर एक सप्ताह के भीतर आता है, और आप इसकी समीक्षा उन प्रश्नों के विरुद्ध करते हैं जिनका आपकी अपनी सहायता टीम जवाब देती रहती है। मैं उस इंजीनियर द्वारा जल्दी ठीक किया जाना पसंद करूंगा जो किनारे के मामलों को जानता है, बजाय इसके कि कुछ पॉलिश और गलत वितरित किया जाए। अंतिम दस्तावेज़ में प्रत्येक उदाहरण आपके API के विरुद्ध निष्पादित किया गया है, इसलिए इसमें कुछ भी महत्वाकांक्षी नहीं है।