अधिकांश API दस्तावेज़ बेकार क्यों हैं (और अपने को कैसे ठीक करें)

आपके API दस्तावेज़ में 47 एंडपॉइंट सूचीबद्ध हैं। प्रत्येक में HTTP मेथड, पथ, रिक्वेस्ट बॉडी और रिस्पॉन्स स्कीमा है। यह पूर्ण, सटीक और पूरी तरह से बेकार है।

क्यों? क्योंकि जब मैं आपके दस्तावेज़ पर आता हूँ, तो मुझे आमतौर पर एंडपॉइंट की सूची नहीं चाहिए।

मैं एक कार्य पूरा करना चाहता हूँ।

मैं जानना चाहता हूँ कि कस्टमर कैसे बनाएँ, पेमेंट मेथड कैसे अटैच करें, सब्सक्रिप्शन कैसे शुरू करें, वेबहुक को कैसे हैंडल करें, विफलता से कैसे उबरें, और इसे सुरक्षित रूप से कैसे टेस्ट करें।

एंडपॉइंट रेफरेंस आवश्यक है। यह उत्पाद नहीं है।

रेफरेंस ऑनबोर्डिंग नहीं है

एक रेफरेंस पेज उत्तर देता है:

• कौन सा पथ मौजूद है
• यह कौन सी मेथड स्वीकार करता है
• कौन से फ़ील्ड अनुमत हैं
• रिस्पॉन्स कैसा दिखता है

ऑनबोर्डिंग उत्तर देती है:

• मुझे पहले क्या करना चाहिए?
• ये कॉल किस क्रम में होती हैं?
• क्या विफल हो सकता है?
• मुझे क्या स्टोर करना चाहिए?
• मैं प्रोडक्शन को तोड़े बिना इसे कैसे टेस्ट करूँ?

यदि आपके दस्तावेज़ में केवल रेफरेंस पेज हैं, तो डेवलपर को कच्चे भागों से वर्कफ़्लो को रिवर्स-इंजीनियर करना होगा।

यही कारण है कि "पूर्ण" दस्तावेज़ अभी भी अनुपयोगी लग सकते हैं।

डेवलपर्स के वास्तविक कार्यों से शुरू करें

अधिकांश APIs के लिए, वास्तविक दस्तावेज़ कार्य पथों से शुरू होने चाहिए:

• एक रिक्वेस्ट को प्रमाणित करें
• पहला संसाधन बनाएँ
• संसाधन को सुरक्षित रूप से अपडेट करें
• एक वेबहुक सुनें
• एक विफल ऑपरेशन को पुनः प्रयास करें
• टेस्ट मोड से प्रोडक्शन में जाएँ

फिर प्रत्येक कार्य एंडपॉइंट रेफरेंस से लिंक कर सकता है।

क्रम मायने रखता है। यदि पहला पृष्ठ एक विशाल रेफरेंस तालिका है, तो आप पाठक से अकेले मानसिक मॉडल बनाने के लिए कह रहे हैं।

एक पूर्ण पथ दिखाएँ, पृथक कॉल नहीं

खराब दस्तावेज़ एक आदर्श रिक्वेस्ट दिखाते हैं:

POST /customers

बेहतर दस्तावेज़ अनुक्रम दिखाते हैं:

1. कस्टमर बनाएँ।
2. सब्सक्रिप्शन बनाएँ।
3. लौटाए गए आईडी स्टोर करें।
4. पुष्टिकरण वेबहुक सुनें।
5. विफलता और रद्दीकरण स्थितियों को हैंडल करें।

डेवलपर्स को इंटीग्रेशन शिप करने के लिए अनुक्रम की आवश्यकता होती है।

इससे भी बेहतर, स्टेट मशीन का आकार शामिल करें:

त्रुटि दस्तावेज़ इंटीग्रेशन का हिस्सा हैं

एक गंभीर API डेवलपर्स को बताता है कि जब चीजें विफल हों तो क्या करना है।

यहाँ मत रुकें:

{ "error": "invalid_request" }

दस्तावेज़ीकृत करें:

• क्या रिक्वेस्ट को पुनः प्रयास करना सुरक्षित है
• क्या ऑपरेशन आंशिक रूप से सफल हो सकता है
• किन त्रुटियों के लिए उपयोगकर्ता कार्रवाई की आवश्यकता है
• किन त्रुटियों के लिए ऑपरेटर कार्रवाई की आवश्यकता है
• सपोर्ट को कौन सी आईडी भेजनी है
• क्या वेबहुक आधिकारिक है

यह वह जगह है जहाँ API दस्तावेज़ विश्वास बुनियादी ढाँचा बन जाते हैं।

प्रोडक्शन वास्तविकता से मेल खाने वाले उदाहरणों का उपयोग करें

यदि प्रोडक्शन वर्कफ़्लो खिलौना नहीं है तो उदाहरण खिलौना नहीं होना चाहिए।

खराब:

{ "name": "John" }

बेहतर:

{
  "externalId": "acct_123",
  "email": "operator@example.com",
  "plan": "studio-audit",
  "metadata": {
    "source": "route-finder",
    "campaign": "content-engine"
  }
}

बेहतर उदाहरण नामकरण, मेटाडेटा, आइडेम्पोटेंसी और एट्रिब्यूशन सिखाता है। यह डेवलपर को वास्तविक चीज़ बनाने में मदद करता है।

प्रोडक्शन से पहले एक चेकलिस्ट जोड़ें

वास्तविक व्यावसायिक प्रभाव वाले प्रत्येक API में गो-लाइव चेकलिस्ट शामिल होनी चाहिए।

यह चेकलिस्ट रेफरेंस को प्रतिस्थापित नहीं करती। यह रेफरेंस को उपयोगी बनाती है।

दस्तावेज़ों को परीक्षण योग्य बनाएँ

सबसे अच्छे API दस्तावेज़ सिस्टम के इतने करीब होते हैं कि जब सिस्टम बदलता है तो वे विफल हो सकते हैं।

इसका मतलब हो सकता है:

• टाइप की गई स्कीमा से उत्पन्न उदाहरण
• CI में मान्य रिक्वेस्ट उदाहरण
• रूट हैंडलर्स के विरुद्ध जाँचा गया OpenAPI आउटपुट
• हर बिल्ड पर जाँचे गए दस्तावेज़ लिंक
• सार्वजनिक वर्कफ़्लो के लिए कॉन्ट्रैक्ट टेस्ट

यदि दस्तावेज़ कोड से दूर मैन्युअल रूप से बनाए रखे जाते हैं, तो वे बह जाएँगे। जब वे बह जाते हैं, तो डेवलपर्स उन पर भरोसा करना बंद कर देते हैं।

मुझे जो संरचना पसंद है

एक गंभीर API के लिए, मैं यह IA शिप करूँगा:

1. यहाँ से शुरू करें: API क्या करता है और आप क्या बना सकते हैं।
2. त्वरित आरंभ: एक पूर्ण हैप्पी पाथ।
3. Auth: कुंजियाँ, स्कोप, रोटेशन, स्थानीय सेटअप।
4. मुख्य वर्कफ़्लो: कार्य-आधारित मार्गदर्शिकाएँ।
5. वेबहुक/ईवेंट: डिलीवरी, पुनः प्रयास, हस्ताक्षर, रीप्ले।
6. त्रुटियाँ/पुनः प्रयास: क्या विफल हुआ और क्या करना है।
7. रेफरेंस: एंडपॉइंट-स्तरीय विवरण।
8. प्रोडक्शन चेकलिस्ट: गो-लाइव गार्डरेल।
9. चेंजलॉग: ब्रेकिंग चेंजेस और माइग्रेशन नोट्स।

यह अतिरेक नहीं है। यह वह है जो किसी को बिना सेल्स इंजीनियर के बैठे इंटीग्रेट करने देता है।