🍎 🏄 🤳 एपीआई स्टाइल गाइड, या उपयोगकर्ताओं को नहीं लगता 🎇 👨‍⚖️ 👩🏽‍🔬

नमस्कार! मेरा नाम लेसा रुतसोई है और मैं व्रीके में एक उत्पाद प्रबंधक हूं। उससे पहले, उन्होंने एडफॉर्म और पांडाडोक में काम किया। पिछले पांच वर्षों से, मैं सब कुछ एकीकरण और एपीआई से संबंधित कर रहा हूं।

व्रीक एक सास सहयोग और परियोजना प्रबंधन उत्पाद है। हम चाहते हैं कि डेवलपर्स Wrike के आधार पर अपने समाधान का निर्माण करें, और इसके लिए हमें अपने एपीआई को सुविधाजनक बनाने की आवश्यकता है। उसी समय, हमारे पास दुनिया भर में 9 कार्यालय हैं, और उनमें से 3 विकास कार्यालय हैं। विभिन्न भाषाओं में बोलने वाली वितरित टीमों का उपयोग करके एक सुसंगत एपीआई बनाना काफी कठिन है। इस बात की संभावना बढ़ रही है कि उनके फैसले एक-दूसरे के खिलाफ होने लगेंगे। इस मामले में, कोई भी सभी के लिए नियमों के एक समान सेट के बिना नहीं कर सकता है।

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

हमें एक सुविधाजनक एपीआई की आवश्यकता क्यों है?

बहुत से पाठकों को संभवत: नहीं-तो-सुविधाजनक एपीआई का उपयोग करके समस्याओं को हल करना था। हां, यह बहुत सरल नहीं है और अधिक समय लगता है, लेकिन आमतौर पर आप अभी भी समस्या को हल कर सकते हैं।

फिर एपीआई को बेहतर बनाने के लिए समय और टीम के प्रयासों को क्यों बर्बाद किया जाए? इसका उत्तर काफी सरल है: बहुत बार आपके उत्पाद के उपयोग के बारे में निर्णय डेवलपर्स द्वारा किया जाता है, खासकर जब यह एपीआई और एकीकरण की बात आती है। इसलिए, न केवल उपयोगकर्ता अनुभव (यूएक्स) के बारे में सोचना महत्वपूर्ण है, बल्कि डीएक्स - डेवलपर अनुभव के बारे में भी।

मैं एक उदाहरण दूंगा। मैंने एक बार एक टीम में काम किया जो सभी उत्पाद एकीकरण के लिए जिम्मेदार थी। अक्सर क्वार्टर के बीच में, जब हमारी योजनाएं पहले से ही उल्लिखित थीं, एक बाज़ारिया आया और उसने कहा: “जेड ने एक नया बाज़ार बनाया है और अपने मंच के अगले संस्करण को जारी करेगा। जल्द ही उनके पास एक शांत सार्वजनिक कार्यक्रम होगा जहां हम अपने एकीकरण और सफलता के बारे में बात कर सकते हैं! यह बहुत अच्छा होगा अगर हम जल्दी से इस एकीकरण को लिखते हैं। ” इस मामले में हमने क्या किया? यदि एक टीम में एक अनुभवी डेवलपर तीन दिनों में न्यूनतम कामकाजी प्रोटोटाइप बना सकता है, तो अक्सर दो या तीन सप्ताह में हम कार्य को सही स्थिति में लाने में कामयाब होते हैं। यदि कुछ दिन गायब थे, तो एपीआई और प्रलेखन ऐसा था।यह हमारे लिए योजनाओं को फिर से तैयार करने और नए एकीकरण का कार्य करने के लिए व्यर्थ था - सभी समान, कुछ भी नहीं उचित तिथि तक काम किया होगा। याद रखें कि आपका उत्पाद ऐसी स्थिति में हो सकता है - साझेदार यह तय करेंगे कि आप अपने एपीआई के साथ कितनी जल्दी और आसानी से काम कर सकते हैं, इस पर निर्भर करता है।

लेकिन शायद ही कोई बुरा एपीआई डिजाइन करना चाहता हो। सबको अलग-अलग क्यों मिलता है? आमतौर पर, एक एपीआई इस तरह विकसित होता है। जब एक स्टार्टअप बढ़ने लगता है और पहले ग्राहक उसके पास आते हैं, तो टीम में से एक अपना समापन बिंदु बनाता है और संस्करण को URL में स्थानांतरित करने का निर्णय लेता है:

धीरे-धीरे नए ग्राहक और नई आवश्यकताएं दिखाई देती हैं। दूसरी टीम के लोग काम में शामिल हैं, जो मानते हैं कि संस्करण के लिए अपने स्वयं के मीडिया प्रकारों का उपयोग करना बेहतर है:

थोड़ी देर बाद, तीसरी टीम आती है। एक सम्मेलन में, वे सीखते हैं कि स्ट्राइप प्रमुख रिलीज की तारीखों के साथ अपने एपीआई का संस्करण बना रहा है। और वे ऐसा करने का निर्णय लेते हैं:

परिणाम एक एपीआई है जिसमें तीन संस्करण विधियां हैं। सभी तरीके काम करते हैं, लेकिन अलग तरीके से काम करते हैं।

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

और तारीखें और समय हैं। मानक दृष्टिकोण का उपयोग करते हुए भी, डेटा को विभिन्न तरीकों से प्रेषित किया जा सकता है: अपने सर्वर के समय क्षेत्र द्वारा, GMT द्वारा, क्लाइंट पर, यूनिक्स समय में। ग्राहकों को सभी डेटा को एक प्रारूप में लाना होगा।

त्रुटि संदेश आम तौर पर सब कुछ अलग तरीके से करते हैं। उदाहरण के लिए, इस तरह:

या इस तरह:

मेरा पसंदीदा त्रुटि संदेश भी है - एक खाली उत्तर:

ठीक है, सिर्फ एक क्लासिक - जवाब 200 ठीक है, जिसके अंदर जो गलत हो गया, उसके विवरण के साथ JSON निहित है।

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

एपीआई बनाने के लिए एक एकल दृष्टिकोण विशेष रूप से वितरित टीमों के साथ बड़ी कंपनियों के लिए महत्वपूर्ण है। यदि कमरे में दस लोग स्टार्टअप बनाते हैं, तो प्रत्येक डेवलपर कंधे पर एक पड़ोसी को दस्तक दे सकता है और कोड की समीक्षा के दौरान मुख्य समस्याओं को सहमत या देख सकता है। एक बड़ी कंपनी में, यह कठिन हो जाता है।

स्टाइल गाइड एपीआई आपको ऐसी समस्याओं को हल करने में मदद करेगा। यह एक दस्तावेज है जो आपके एपीआई के डिजाइन सिद्धांतों का वर्णन करता है। यदि हर कोई समान दृष्टिकोण का उपयोग करता है, तो ऐसा लगता है कि एपीआई को एक व्यक्ति द्वारा विकसित किया गया था, न कि कई अलग-अलग टीमों द्वारा। यह दृष्टिकोण कोड स्टाइल गाइड की तरह है जब टीम इस बात पर सहमत होती है कि वे कोड कैसे लिखते हैं। एक टीम का एक व्यक्ति दूसरी टीम के कोड आधार को देख सकता है और जल्दी से समझ सकता है कि वहां क्या हो रहा है।

अपना खुद का एपीआई स्टाइल गाइड कैसे बनाएं?

Arnauld Lauret ( एपीआई अप्रेंटिस के रूप में जाना जाता है ) ने एक शांत साइट बनाई - एपीआई स्टाइलबुक । उन्होंने सार्वजनिक रूप से सुलभ स्टाइल गाइड को रखा, जिसे विभिन्न कंपनियों (सिस्को, Google, रेड हैट, सरकारी एजेंसियों और कई अन्य) ने सार्वजनिक डोमेन में डाल दिया।

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

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

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

स्टाइल गाइड एपीआई में और क्या शामिल करना है

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

वे क्या हो सकते हैं?

Write APIs in English. , . - , , . Style Guide, , .
API First principle. API : , , frontend-. , API . , , .
REST और JSON का उपयोग करें। यह महत्वपूर्ण हो सकता है यदि आप चाहते हैं कि व्यापक दर्शक आपके एपीआई या प्लेटफॉर्म का उपयोग करें। इस तथ्य के बावजूद कि 2017 के बाद से ग्राफ़िकल तेजी से लोकप्रिय हो गया है, हर कोई इसके बारे में नहीं जानता है। अधिकांश डेवलपर्स, सबसे अधिक संभावना है, कभी भी इसका उपयोग नहीं किया है, जिसका अर्थ है कि वे विसर्जन और विकास के लिए समय बढ़ाएंगे। जटिलता क्यों पैदा करें?

इसके अलावा, मूल सिद्धांतों को विषयों पर रखा जा सकता है। उदाहरण के लिए, REST और JSON के उपयोग के सिद्धांत के अंदर, आप आसानी से यह निर्धारित कर सकते हैं कि गाइड में किन विषयों का वर्णन किया जाना चाहिए:

JSON पेलोड के साथ बाकी एपीआई को प्राथमिकता दें
- HTTP अनुरोध
- HTTP स्थिति कोड
- Json

प्रत्येक विषय पर आगे, आप उन नियमों के साथ आ सकते हैं जिन्हें कंपनी की सभी टीमों को पालन करना चाहिए:

HTTP अनुरोध
- जरूरी HTTP तरीकों का सही इस्तेमाल करें
- कस्टम HTTP हेडर SHOULD नामकरण सम्मेलन का अनुसरण करते हैं

मुझे वास्तव में यह दृष्टिकोण पसंद है जो नियमों का पालन करने की आवश्यकता का वर्णन करता है क्रियाओं के ज़रिए MUST, SHOULD, या MAY ( RFC 2119 से उधार लिया हुआ )। फिर स्टाइल गाइड पढ़ने वाले सभी अनिवार्य नियमों और सिफारिशों के बीच अंतर करेंगे।

उदाहरण के लिए, यह ज़ालैंडो में कैसा दिखता है :

स्टाइल गाइड शुरू करते समय ध्यान रखने योग्य बातें

. , . , , . , , . API management , . API.
. - 15- . rate limiting, .. — , , - .
. , OAuth, REST. , , , scopes .
. , , .
. , . , . . . , .
. , , .
. , , .. : , «user», , «user», .
. , — . , (OpenAPI-, -) . .

API Style Guide?

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

पहले आपको हितधारकों को समझाने की जरूरत है। और यहां हम अक्सर विभिन्न क्षेत्रों और व्यापार प्रतिनिधियों में दोनों तकनीकी नेताओं के बारे में बात कर रहे हैं। हर किसी को समझना चाहिए कि हम किन समस्याओं को हल करना चाहते हैं और स्टाइल गाइड कैसे मदद कर सकते हैं। मेरे उदाहरण में, सभी हितधारकों ने समझा कि एक अच्छा एपीआई एक महत्वपूर्ण लाभ है। कई ग्राहक इस तरह के अनुरोध के साथ आए थे, और प्रतियोगियों ने नहीं किया और सक्रिय रूप से अपने एपीआई के माध्यम से उपलब्ध अवसरों के दायरे का विस्तार किया।

अगला कदम एक टीम ढूंढना है जो ऐसा करेगी। मेरे मामले में, कंपनी के पास पहले से ही एक अलग टीम थी जो बाहरी एपीआई का समर्थन करती थी। उसने बदलाव की आवश्यकता को सबसे अच्छी तरह से समझा, क्योंकि वह लगातार अपने काम में कठिनाइयों का सामना कर रही थी। इस टीम के सदस्य परियोजना में भाग लेने से प्रसन्न थे।

टीम ने स्टाइल गाइड एपीआई को कैसे लागू किया?

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

एक बड़ी कंपनी में एक टीम के लिए इस तरह के महत्वपूर्ण बदलावों को लागू करना बहुत मुश्किल है। सहयोग की आवश्यकता। यहां एपीआई चैंपियन जुड़े हुए थे - प्रत्येक दिशा के आर्किटेक्ट और टेकलाइड्स जिन्होंने विचार को अपनी टीमों और डिवीजनों में एकीकृत करने में मदद की।

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

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

इसके अलावा, एपीआई चैंपियन ने अपने क्षेत्रों में समीक्षा करने में मदद की। उनकी टीमों के लोगों ने पहले उनकी ओर रुख किया, और फिर अंतिम समीक्षा उस टीम द्वारा की गई जो स्टाइल गाइड बना रही थी।

कुछ समय बाद, कंपनी में एक एपीआई समुदाय बनने लगा। इसमें ऐसे लोग शामिल थे, जिन्होंने कई समीक्षा चक्रों के माध्यम से जाना, यह पता लगाया कि एक अच्छा और सही डिज़ाइन क्या है, इसकी आवश्यकता क्यों है और इसे कैसे बनाया जाए। हमने एक बड़ी चैट बनाई जिसमें हर कोई एक सवाल पूछ सकता था, और एपीआई समुदाय के सदस्यों ने इसे हल करने में मदद की।

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

हमने कंपनी की अधिकांश टीमों को ऑन-इंजीनियरिंग करने की कोशिश की, जिसमें गैर-इंजीनियरिंग वाले भी शामिल हैं। यह भी आवश्यक है ताकि हर कोई यह समझे कि कब, किन मामलों में और किसके लिए आप मदद के लिए आ सकते हैं।

स्वचालन

अंतिम महत्वपूर्ण विषय नियमित प्रक्रियाओं का स्वचालन है। समीक्षा एक प्रमुख उदाहरण के रूप में काम कर सकती है। बड़ी संख्या में टीमों के साथ एक बड़ी कंपनी में, सबसे अधिक संभावना है, आपको बहुत सारी समीक्षा करने की आवश्यकता होगी। मैं एक लापता त्रुटि विवरण या एक गलत आईडी प्रारूप जैसी बुनियादी समस्याओं पर समय बर्बाद करने की तरह महसूस नहीं करता।

कुछ उपकरण इसके साथ मदद कर सकते हैं:

Zalando से Zally यह देखने के लिए जाँच करता है कि OpenAPI विनिर्देश आपके API स्टाइल गाइड से मेल खाता है या नहीं। Zalando स्टाइल गाइड के अनुपालन के लिए Zally का मूल कॉन्फ़िगरेशन चेक करता है, लेकिन आप अपने नियमों को फिर से परिभाषित और जोड़ सकते हैं।
Apiary's Dredd यह देखने के लिए जाँच करता है कि क्या अंतिम REST API कार्यान्वयन आपके डिज़ाइन से मेल खाता है, जैसे कि OpenAPI, ब्लूप्रिंट या RAML विनिर्देशन।

यह लेख Miro के प्लेटफ़ॉर्म डेवलपर्स सम्मेलन के साथ मेरी बात का एक प्रतिलेख है । आप भाषण का वीडियो यहां पा सकते हैं ।

मुझे एपीआई स्टाइल गाइड को लागू करने के बारे में आपके सवालों का जवाब देने में खुशी होगी। यदि आप एक समान अनुभव साझा करते हैं तो यह भी अच्छा होगा!

इस लेख को तैयार करने में उनकी मदद के लिए डारिया इवानोवा का विशेष धन्यवाद!