REST API के लिए ऑनलाइन प्रलेखन को संरचित करना

Question

मैं अपना पहला रेस्ट एपीआई बना रहा हूं जो JSON और XML फॉर्मेट में डेटा को क्रमबद्ध करता है। मैं एपीआई क्लाइंट को एक इंडेक्स पेज प्रदान करना चाहूंगा, जहां वे कार्यान्वित एंडपॉइंट चुन सकेंगे।

अपनी API को सबसे उपयोगी बनाने के लिए मुझे किस जानकारी को शामिल करने की आवश्यकता है, और मुझे इसे कैसे व्यवस्थित करना चाहिए?

Answer 1

यह एक सरल जवाब के लिए एक बहुत ही जटिल प्रश्न है।

आप मौजूदा API फ्रेमवर्क, जैसे स्वैगर स्पेसिफिकेशन ( OpenAPI ), और apiary.io और apiblueprint.org जैसी सेवाओं पर एक नज़र रखना चाहते हैं ।

इसके अलावा, यहां एक ही REST API का उदाहरण दिया गया है, जो तीन अलग-अलग तरीकों से व्यवस्थित और व्यवस्थित है। मौजूदा सामान्य तरीकों से सीखना आपके लिए एक अच्छी शुरुआत हो सकती है।

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

मुझे लगता है कि गुणवत्ता शीर्ष स्तर पर REST API डॉक्स के लिए निम्न स्तर की आवश्यकता होती है:

• आपके सभी एपीआई एंडपॉइंट्स की सूची (आधार / रिश्तेदार URL)
• प्रत्येक समापन बिंदु के लिए इसी HTTP GET / POST / ... विधि प्रकार
• अनुरोध / प्रतिक्रिया MIME- प्रकार (कैसे पार्स और पार्स उत्तरों को सांकेतिक शब्दों में बदलना)
• HTTP हेडर सहित एक नमूना अनुरोध / प्रतिक्रिया
• सभी प्रकार के लिए निर्दिष्ट प्रकार और प्रारूप, जिनमें URL, निकाय और शीर्षलेख शामिल हैं
• एक संक्षिप्त पाठ विवरण और महत्वपूर्ण नोट्स
• एक छोटा कोड स्निपेट जो लोकप्रिय वेब प्रोग्रामिंग भाषाओं में समापन बिंदु का उपयोग दिखा रहा है

इसके अलावा बहुत सारे JSON / XML- आधारित डॉक्टर फ्रेमवर्क हैं जो आपकी API परिभाषा या स्कीमा को पार्स कर सकते हैं और आपके लिए डॉक्स का सुविधाजनक सेट उत्पन्न कर सकते हैं। लेकिन डॉक जनरेशन सिस्टम का चुनाव आपकी परियोजना, भाषा, विकास के माहौल और कई अन्य चीजों पर निर्भर करता है।