17. इंटीग्रेशन API और API कुंजियाँ

इंटीग्रेशन API की मदद से आपका अपना प्रोग्राम, स्प्रेडशीट या स्क्रिप्ट आपके प्रोजेक्ट का डेटा अपने-आप पढ़ सकती है: प्रोजेक्ट सूची, केबल और सामग्री की सूचियाँ, वितरण बोर्डों की सर्किट तालिका और टर्मिनल सूची, मात्रा-विवरण और ड्रॉइंग पैकेज का संयोजन। API केवल पढ़ने वाली है: यह ड्रॉइंग या प्रोजेक्ट में कोई बदलाव नहीं करती।

API कुंजी कौन पा सकता है

API की पहुँच संचालक द्वारा हर खाते के लिए अलग से चालू की जाती है। जब आपके खाते को पहुँच मिल जाती है, तो प्रोफ़ाइल पृष्ठ पर API कुंजियाँ कार्ड दिखाई देता है; पहुँच न होने पर यह कार्ड छिपा रहता है। एक खाते की एक समय में अधिकतम 5 सक्रिय कुंजियाँ हो सकती हैं।

कुंजी वही प्रोजेक्ट देखती है जो आप देखते हैं: आपके अपने प्रोजेक्ट, और अनुरोध करने पर वे जो आपके साथ साझा किए गए हैं। साझा किए गए प्रोजेक्ट की सूचियाँ और मात्रा-विवरण तभी लौटाए जाते हैं जब साझाकरण निर्यात की अनुमति देता हो।

कुंजी बनाना

प्रोफ़ाइल पृष्ठ के API कुंजियाँ कार्ड पर नई कुंजी बटन पर क्लिक करें।
कुंजी को एक नाम दें (उदाहरण के लिए उस प्रोग्राम का नाम जो इसका उपयोग करेगा)।
दायरा चुनें: प्रोजेक्ट पढ़ना प्रोजेक्ट सूची और प्रोजेक्ट का डेटा देता है, दस्तावेज़ पढ़ना सूचियाँ, मात्रा-विवरण और ड्रॉइंग पैकेज देता है। केवल वही चुनें जिसकी प्रोग्राम को वास्तव में ज़रूरत है।
समाप्ति चुनें: 30, 90 या 365 दिन। समाप्त हो चुकी कुंजी काम करना बंद कर देती है; उसकी जगह नई कुंजी बनाएँ।
अपना वर्तमान पासवर्ड दर्ज करें (बिना पासवर्ड वाले खाते के लिए ताज़ा साइन-इन ज़रूरी है)। पहली कुंजी के लिए API उपयोग की शर्तें स्वीकार करें।

बनाने के बाद कुंजी केवल एक बार दिखाई जाती है: इसे कॉपी करें और किसी सुरक्षित स्थान पर रखें। बाद में सूची में केवल इसका उपसर्ग (avk_…) दिखता है, साथ में बनाने और समाप्ति की तारीखें, अंतिम उपयोग और कॉल की संख्या। नई कुंजी के बारे में हम एक ईमेल सूचना भी भेजते हैं (कुंजी के बिना)।

कुंजी रद्द करना

कार्ड पर कुंजी के बगल में रद्द करें बटन कुंजी को तुरंत अनुपयोगी बना देता है; इसे वापस नहीं किया जा सकता। जब आप कुंजी का उपयोग न करें, जब उसका उपयोग करने वाले प्रोग्राम को बंद कर रहे हों, या जब आपको शक हो कि वह लीक हो गई है, तो कुंजी रद्द करें।

सुरक्षा सुझाव

कुंजी को अपने पासवर्ड की तरह सँभालें: जो भी इसे जानता है, वह इसके दायरे में आपके प्रोजेक्ट पढ़ सकता है।
इसे सोर्स कोड में नहीं, गुप्त जानकारी के भंडार में रखें (पासवर्ड मैनेजर, सर्वर का एनवायरनमेंट वेरिएबल या CI का गुप्त वेरिएबल): इसे git रिपॉज़िटरी में कभी कमिट न करें, साझा स्प्रेडशीट या ईमेल में भी न डालें।
ब्राउज़र में चलने वाले कोड में इसका उपयोग न करें (वेब पेज, ब्राउज़र एक्सटेंशन): वहाँ कोई भी इसे पढ़ सकता है। कुंजी की जगह सर्वर, स्क्रिप्ट या डेस्कटॉप प्रोग्राम में है।
हर प्रोग्राम को उसकी अपनी कुंजी दें, जितना संभव हो सबसे छोटे दायरे और कम समाप्ति अवधि के साथ; इस तरह एक कुंजी रद्द करने से कुछ और बंद नहीं होता।

प्रोग्राम से उपयोग

कुंजी अनुरोध के हेडर में Bearer टोकन के रूप में भेजी जाती है: Authorization: Bearer avk_…। एंडपॉइंट /api/v1/ के अंतर्गत हैं (उदाहरण के लिए GET /api/v1/projects) और उत्तर JSON में देते हैं। OpenAPI प्रारूप में पूरा विवरण /api/v1/openapi.json पर उपलब्ध है; अधिकांश डेवलपर टूल इसे आयात कर सकते हैं।

कॉल की संख्या प्रति कुंजी और प्रति खाता सीमित है (डिफ़ॉल्ट रूप से प्रति मिनट 60 और प्रतिदिन 10,000); इससे ऊपर सर्वर 429 के साथ उत्तर देता है, ऐसे में थोड़ा इंतज़ार करें। वेबसाइट पर साइन-इन (कुकी) API को नहीं खोलता, और कुंजी आपको वेब इंटरफ़ेस में साइन-इन नहीं कराती।