एक एपीआई केवल उसके प्रलेखन के रूप में अच्छा है, इसलिए सुनिश्चित करें कि आपका उच्च गुणवत्ता वाले निर्देशों और अन्य महत्वपूर्ण विवरण के साथ खोजा जा सकता है।
अधिक संगठन अपने व्यवसाय को अनुकूलित करने के लिए एपीआई की शक्ति का लाभ उठा रहे हैं। एपीआई मूल्य अनलॉक करने और एक अतिरिक्त सेवा प्रदान करने का एक तरीका बन गया है।
उनकी सामान्य लोकप्रियता के बावजूद, हर एपीआई सफल नहीं होता है। किसी एपीआई को अपनाना और उसका उपयोग काफी हद तक उसकी सफलता को निर्धारित करता है। गोद लेने में वृद्धि करने के लिए, आपके एपीआई को खोजने और उपयोग करने में आसान होना चाहिए।
ऐसा करने का सबसे अच्छा तरीका है कि आप अपने एपीआई का विस्तार से दस्तावेजीकरण करें। इसमें उन्हें समझने में आसान बनाने के लिए महत्वपूर्ण घटकों का विवरण शामिल है। कुछ घटकों का पता लगाएं, जिन्हें आपको अपने एपीआई दस्तावेज़ में शामिल करना चाहिए।
एपीआई दस्तावेज क्या है?
एपीआई दस्तावेज तकनीकी सामग्री है जो एक एपीआई का विस्तार से वर्णन करता है। यह एक मैनुअल है जिसमें एपीआई के साथ काम करने के लिए आवश्यक सभी जानकारी है। दस्तावेज़ में एपीआई जीवनचक्र और इसके घटकों को एकीकृत करने और उपयोग करने के निर्देश शामिल हैं।
एपीआई प्रलेखन में संसाधन विवरण, समापन बिंदु, विधियाँ, अनुरोध और प्रतिक्रिया उदाहरण शामिल हैं। इसमें प्रैक्टिकल गाइड और ट्यूटोरियल भी शामिल हो सकते हैं जो उपयोगकर्ताओं को दिखाते हैं कि इसे कैसे एकीकृत किया जाए। प्रत्येक अनुभाग की खोज करने से उपयोगकर्ताओं को एपीआई को एकीकृत करने और उपयोग करने की ठोस समझ मिलती है।
Google डॉक्स जैसे संपादकों को एक बार पेशेवर एपीआई दस्तावेज़ों के लिए व्यापक रूप से उपयोग किया जाता था। आजकल, दस्तावेज़ 360, कॉन्फ्लुएंस और गिटहब पेज जैसे अधिक उन्नत टूल हैं। ये टूल आसान वर्कफ़्लोज़ के लिए टेक्स्ट और कोड को एकीकृत करने में मदद करते हैं।
1. एपीआई का अवलोकन और उद्देश्य
एपीआई के दस्तावेजीकरण में पहला कदम उपयोगकर्ताओं को यह बताना है कि यह किस बारे में है। इसके द्वारा प्रदान किए जाने वाले संसाधनों के प्रकार के बारे में जानकारी शामिल करें। एपीआई के पास आमतौर पर विभिन्न संसाधन होते हैं जो वे लौटाते हैं, इसलिए उपयोगकर्ता अनुरोध कर सकता है कि उन्हें क्या चाहिए।
विवरण संक्षिप्त है, आमतौर पर एक से तीन वाक्य जो संसाधन का वर्णन करते हैं। उपलब्ध संसाधन, समापन बिंदु और प्रत्येक समापन बिंदु से जुड़ी विधियों का वर्णन करें। एपीआई डेवलपर के रूप में, आप इसके घटकों, कार्यक्षमता और उपयोग के मामले का सबसे अच्छा वर्णन करते हैं।
यहाँ Airbnb API के विवरण का एक उदाहरण दिया गया है:
2. प्रमाणीकरण और प्राधिकरण के तरीके
एपीआई हजारों अनुरोधों और भारी मात्रा में डेटा को संभालते हैं। प्रमाणीकरण आपके एपीआई के डेटा को सुनिश्चित करने के तरीकों में से एक है और उपयोगकर्ता हैकर्स से सुरक्षित हैं। एपीआई प्रमाणीकरण उपयोगकर्ता की पहचान की पुष्टि करता है और उन्हें संसाधनों तक पहुंच प्रदान करता है।
सुनिश्चित करने के कई तरीके हैं समापन बिंदु सुरक्षा. अधिकांश एपीआई एक एपीआई कुंजी का उपयोग करते हैं। यह वर्णों की एक स्ट्रिंग है जिसे उपयोगकर्ता वेबसाइट से उत्पन्न कर सकता है और प्रमाणीकरण के लिए उपयोग कर सकता है।
एपीआई प्रलेखन को उपयोगकर्ताओं को उनकी पहचान को प्रमाणित और अधिकृत करने के बारे में मार्गदर्शन करना चाहिए। निम्न आरेख Twitter API प्रमाणीकरण जानकारी दिखाता है।
3. एंडपॉइंट्स, यूआरआई पैटर्न और एचटीटीपी तरीके
इस खंड में, संसाधन तक पहुँचने का तरीका प्रदर्शित करें। समापन बिंदु केवल पथ का अंत दिखाते हैं, इसलिए उनका नाम। वे संसाधन तक पहुंच दिखाते हैं और HTTP तरीके समापन बिंदु GET, POST या DELETE के साथ इंटरैक्ट करता है।
एक संसाधन में विभिन्न प्रकार के अंत बिंदु होने की संभावना है। प्रत्येक एक अलग पथ और विधि के साथ। एंडपॉइंट्स में आमतौर पर उनके उद्देश्य और यूआरएल पैटर्न का संक्षिप्त विवरण होता है।
निम्न कोड नमूना Instagram पर GET उपयोगकर्ता समापन बिंदु दिखाता है।
मुझे मिलना? फ़ील्ड्स = {फ़ील्ड} और एक्सेस_टोकन = {एक्सेस-टोकन}4. अनुरोध और प्रतिक्रिया प्रारूप
आपको अनुरोध और प्रतिक्रिया स्वरूपों का दस्तावेजीकरण करना होगा ताकि उपयोगकर्ता जान सके कि क्या उम्मीद करनी है। अनुरोध एक संसाधन के लिए पूछने वाले क्लाइंट का URL है, जबकि प्रतिक्रिया सर्वर से प्रतिक्रिया है।
निम्नलिखित एक नमूना अनुरोध है जिसे आप LinkedIn API को भेज सकते हैं।
पाना https://api.linkedin.com/v2/{service}/1234और यहाँ एक नमूना प्रतिक्रिया है कि यह वापस आ सकता है:
{
"आईडी": 1234,
"संबंधित इकाई": "कलश: ली: संबंधित इकाई: 6789"
}5. पैरामीटर और हेडर
आपको अपने समापन बिंदुओं के मापदंडों का भी दस्तावेजीकरण करना चाहिए, जो कि ऐसे विकल्प हैं जिन्हें आप उन्हें पास कर सकते हैं। पैरामीटर एक आईडी या संख्या हो सकती है जो प्रतिक्रिया में लौटाए गए डेटा की मात्रा या प्रकार को निर्दिष्ट करती है।
हेडर, पथ और क्वेरी स्ट्रिंग पैरामीटर सहित विभिन्न प्रकार के पैरामीटर हैं। समापन बिंदुओं में विभिन्न प्रकार के पैरामीटर हो सकते हैं।
आप HTTP अनुरोध शीर्षलेख के रूप में कुछ पैरामीटर शामिल कर सकते हैं। आमतौर पर, ये एपीआई कुंजी जैसे प्रमाणीकरण उद्देश्यों के लिए होते हैं। यहां एपीआई कुंजियों वाले हेडर का उदाहरण दिया गया है:
हेडर: {
'X-RapidAPI-कुंजी': 'fd40ada866msh4d8b69e4aa2dd19p12e47fjsn7efdcbc75635',
'X-RapidAPI-Host': 'wft-geo-db.p.rapidapi.com'
}
आप अंत बिंदु के मुख्य भाग में URL पर पथ पैरामीटर शामिल करते हैं। वे एक उपयोगकर्ता को दिखाते हैं कि मापदंडों को कैसे और कहाँ रखा जाए और प्रतिक्रिया कैसे दिखाई देगी। कर्ली ब्रेसिज़ में शब्द पैरामीटर हैं।
आप पथ पैरामीटर का प्रतिनिधित्व करने के लिए कोलन या अन्य सिंटैक्स का भी उपयोग कर सकते हैं।
/service/myresource/user/{user}/bicycles/{bicycleId}क्वेरी पैरामीटर के साथ, आपको समापन बिंदु पर क्वेरी से पहले एक प्रश्न चिह्न (?) लगाना होगा। उसके बाद प्रत्येक पैरामीटर को एम्परसेंड (&) से अलग करें। माइक्रोसॉफ्ट के पास ग्राफ एपीआई पर अच्छा दस्तावेज है।
6. त्रुटि कोड और त्रुटि प्रबंधन
कभी-कभी HTTP अनुरोध विफल हो जाते हैं, जो उपयोगकर्ता को भ्रमित कर सकता है। उपयोगकर्ताओं को त्रुटियों को समझने में मदद करने के लिए दस्तावेज़ीकरण में अपेक्षित त्रुटि कोड शामिल करें।
लिंक्डइन त्रुटि से निपटने के लिए मानक HTTP त्रुटि कोड प्रदान करता है:
7. नमूना कोड स्निपेट
कोड स्निपेट आपके दस्तावेज़ के आवश्यक भाग हैं। वे उपयोगकर्ताओं को दिखाते हैं कि एपीआई को विभिन्न भाषाओं और प्रारूपों में कैसे एकीकृत किया जाए। प्रलेखन में विभिन्न भाषाओं में एसडीके (सॉफ्टवेयर डेवलपमेंट किट) को स्थापित और एकीकृत करने का तरीका शामिल करें।
रैपिडएपीआई में डेवलपर्स के लिए कोड स्निपेट के अच्छे उदाहरण हैं:
9. एपीआई वर्जनिंग और चेंज लॉग
एपीआई वर्जनिंग इसका एक अनिवार्य हिस्सा है एपीआई डिजाइन. यह आपके उपयोगकर्ताओं को निर्बाध सेवाओं की डिलीवरी सुनिश्चित करता है। वर्जनिंग क्लाइंट एप्लिकेशन को प्रभावित किए बिना एपीआई को नए संस्करणों के साथ बढ़ा सकती है।
उपयोगकर्ता पुराने संस्करणों का उपयोग करना जारी रख सकते हैं या समय के साथ उन्नत संस्करणों में माइग्रेट कर सकते हैं। यदि लॉग में नए परिवर्तन हैं, तो उन्हें दस्तावेज़ीकरण में शामिल करें ताकि उपयोगकर्ता जागरूक हों।
Microsoft ग्राफ़ API में अच्छी तरह से प्रलेखित परिवर्तन लॉग हैं:
अंत में, समर्थन और प्रतिक्रिया के लिए दस्तावेज़ीकरण में महत्वपूर्ण संपर्कों को शामिल करें। ये सुनिश्चित करते हैं कि उपयोगकर्ता आप तक त्रुटि रिपोर्ट और एपीआई को बेहतर बनाने के बारे में जानकारी के साथ पहुंच सकें।
एपीआई प्रलेखन का मूल्य
यदि आप वाणिज्यिक मूल्य के लिए एपीआई बनाते हैं, तो खपत इसकी सफलता निर्धारित करती है। और उपयोगकर्ताओं को आपके एपीआई का उपभोग करने के लिए, उन्हें इसे समझना चाहिए।
प्रलेखन जीवन के लिए एक एपीआई लाता है। यह घटकों को सरल भाषा में विस्तार से समझाता है जो उपयोगकर्ताओं को इसके मूल्य और उपयोग को बेचता है। यदि उपयोगकर्ता के पास अच्छा डेवलपर अनुभव है तो उपयोगकर्ता खुशी से आपके एपीआई का उपभोग करेंगे।
अच्छा प्रलेखन भी एपीआई के रखरखाव और स्केलिंग को आसान बनाने में मदद करता है। एपीआई के साथ काम करने वाली टीमें इसे प्रबंधित करने के लिए दस्तावेज़ीकरण का उपयोग कर सकती हैं।