एपीआई डिजाइन: ठोस बनाम अमूर्त दृष्टिकोण

25

जब सिस्टम (व्यावसायिक स्तर पर) के बीच एपीआई पर चर्चा करते हैं, तो हमारी टीम में अक्सर दो अलग-अलग दृष्टिकोण होते हैं: कुछ लोग अधिक पसंद करते हैं - कहते हैं - ~~सामान्य~~ सार दृष्टिकोण, अन्य सीधे "ठोस" दृष्टिकोण।

उदाहरण: एक साधारण "व्यक्ति खोज" एपीआई का डिज़ाइन। ठोस संस्करण होगा

 searchPerson(String name, boolean soundEx,
              String firstName, boolean soundEx,
              String dateOfBirth)

कंक्रीट संस्करण के पक्ष में लोग कहते हैं:

एपीआई स्व-दस्तावेजीकरण है
इसे समझना आसान है
इसे सत्यापित करना आसान है (संकलक या एक webservice: स्कीमा सत्यापन के रूप में)
चुम्मा

हमारी टीम के अन्य लोगों का कहना है कि "यह खोज मानदंडों की एक सूची है"

searchPerson(List<SearchCriteria> criteria)

साथ में

SearchCritera {
  String parameter,
  String value,
  Map<String, String> options
}

संभवतः कुछ गणन प्रकार के "पैरामीटर" बनाने के साथ।

समर्थकों का कहना है:

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

प्रतिवाद है

वैध मापदंडों और वैध पैरामीटर संयोजनों के बारे में बहुत सारे दस्तावेज
अधिक संचार प्रयास क्योंकि अन्य टीमों के लिए इसे समझना अधिक कठिन है

क्या कोई सर्वोत्तम प्रथाएं हैं? साहित्य?

api web-services api-design

— एरिक
स्रोत

3

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

— gnat

"ठोस" के विपरीत "सामान्य" नहीं है, यह "सार" है। लाइब्रेरी या एपीआई के लिए अमूर्तता बहुत महत्वपूर्ण है, और यह चर्चा वास्तव में मौलिक प्रश्न पूछने में विफल हो रही है, इसके बजाय यह तय करना कि जो शैली का एक बहुत ही तुच्छ प्रश्न है। FWIW, विकल्प बी के लिए तर्क-वितर्क FUD के एक लोड की तरह लगता है, आपको किसी भी अतिरिक्त दस्तावेज या संचार की आवश्यकता नहीं होनी चाहिए अगर एपीआई डिज़ाइन आधा साफ है और ठोस सिद्धांतों का पालन करता है।

— एरोन ने

@ बाहर का इशारा करने के लिए धन्यवाद। ("सार")। यह एक अनुवाद मुद्दा हो सकता है, जर्मन में "उदार" मुझे अभी भी ठीक लगता है। आपके लिए "वास्तव में मौलिक प्रश्न" क्या है?

— इरिक

4

@ चेतावनी: प्रश्न सार के बारे में नहीं है। सही सुधार यह होगा कि "सामान्य" के विपरीत "विशिष्ट" है, "ठोस" नहीं।

— Jan Hudec

इसके लिए एक और वोट जेनेरिक बनाम अमूर्त के बारे में नहीं है, लेकिन जेनेरिक बनाम विशिष्ट है। ऊपर "ठोस" उदाहरण वास्तव में नाम, फर्स्टनाम और डेटऑफ बर्थ के लिए विशिष्ट है, अन्य उदाहरण किसी भी पैरामीटर के लिए सामान्य है। न ही विशेष रूप से अमूर्त हैं। मैं शीर्षक संपादित करूंगा, लेकिन मैं एक संपादित युद्ध शुरू नहीं करना चाहता हूं :-)

— मैट फ्रिके

18

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

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

— कार्ल बेवफेल्ड
स्रोत

7

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

चंद्रमा के नीचे शायद ही कभी नई चीजें होती हैं। पूर्व कला, विशेष रूप से स्थापित मानकों और स्वरूपों पर एक नज़र डालें (उदाहरण के लिए, फ़ीड्स के बाद कई चीजों को मॉडल किया जा सकता है, घटना विवरण ical / vcal में विस्तृत थे)। अपने एपीआई को आसानी से जोड़ दें, जहां लगातार और सर्वव्यापी संस्थाएं ठोस हैं और कल्पना विस्तार शब्दकोष हैं। विशिष्ट स्थितियों से निपटने के लिए कुछ अच्छी तरह से स्थापित पैटर्न भी हैं। उदाहरण के लिए, HTTP रिक्वेस्ट (और समान) को हैंडल और रिस्पॉन्स ऑब्जेक्ट के साथ एपीआई में मॉडल किया जा सकता है।

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

कभी-कभी, अमूर्त होने से जटिलता को कम करने में मदद मिलती है: भले ही आप केवल 3 + 4, 2 + 2, और 7 + 6 को जोड़ने के लिए एक कैलकुलेटर डिज़ाइन करते हैं, एक्स + वाई को लागू करने के लिए एक्स और वाई के साथ तकनीकी रूप से व्यवहारिक सीमाएं बहुत सरल हो सकती हैं। Y, और ADD_3_4 (), ADD_2_2 (), ... के बजाय अपने API में ADD (X, Y) शामिल करें ...

सभी के सभी, एक तरह से या किसी अन्य को चुनना एक तकनीकी विवरण है। आपके दस्तावेज़ को लगातार उपयोग के मामलों का ठोस तरीके से वर्णन करना चाहिए।

आप डेटा संरचना पक्ष पर जो कुछ भी करते हैं, वह एपीआई संस्करण के लिए एक क्षेत्र प्रदान करता है।

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

साहित्य की ओर से मैं "ब्यूटीफुल कोड" की सिफारिश कर सकता हूं। प्रोग्रामर बताते हैं कि वे एंडी ओरम, ग्रेग विल्सन द्वारा कैसे सोचते हैं, क्योंकि मुझे लगता है कि सुंदरता छिपी हुई इष्टतमता (और किसी उद्देश्य के लिए उपयुक्तता) के बारे में है।

— रोमन सूसी
स्रोत

1

मेरी व्यक्तिगत प्राथमिकता सार है, फिर भी मेरी कंपनी की नीतियां मुझे ठोस होने में रोकती हैं। यह मेरे लिए बहस का अंत है :)

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

यहाँ दो दृष्टिकोण हैं जिनका मैं विरोध करने के दृष्टिकोण के साथ था:

एहसान सार कक्षाएं

अनुकूल भाव

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

— gws2
स्रोत

1

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

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

— Pavels
स्रोत

1

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

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

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

— जान हुदेक
स्रोत

1

मैं सार इंटरफ़ेस दृष्टिकोण का पक्ष लूंगा। उन प्रकार की (खोज) सेवा के लिए एक प्रश्न रखना एक सामान्य समस्या है और संभवतः फिर से घटित होगी। इसके अलावा आप संभवतः अधिक सेवा वाले उम्मीदवारों को पाएंगे जो अधिक सामान्य इंटरफ़ेस का पुन: उपयोग करने के लिए उपयुक्त हैं। उन सेवाओं के लिए एक सुसंगत सामान्य इंटरफ़ेस प्रदान करने में सक्षम होने के लिए मैं इंटरफ़ेस परिभाषा में वर्तमान में पहचाने गए क्वेरी मापदंडों की गणना नहीं करूंगा।

जैसा कि यह पहले बताया गया था - मुझे इंटरफ़ेस को संशोधित किए बिना कार्यान्वयन को बदलने या विस्तारित करने का अवसर पसंद है। एक और खोज मापदंड जोड़ना सेवा परिभाषा में परिलक्षित नहीं होता है।

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

— 0x0me
स्रोत

1

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

अच्छा एपीआई

गलत होना असंभव है।
संकलक / लिंकर आपको गलत नहीं होने देगा।
संकलक चेतावनी देगा यदि आप इसे गलत पाते हैं।
स्पष्ट उपयोग सही है (शायद)।
नाम आपको बताता है कि इसका उपयोग कैसे करना है।
इसे सही करें या यह हमेशा रनटाइम पर टूट जाएगा।
आम सम्मेलन का पालन करें और आप इसे सही कर लेंगे।
प्रलेखन पढ़ें और आप इसे सही समझेंगे।
कार्यान्वयन पढ़ें और आपको यह सही लगेगा।
सही मेलिंग सूची धागे को पढ़ें और आप इसे सही कर लेंगे।

खराब एपीआई

मेलिंग लिस्ट थ्रेड को पढ़ें और आपको यह गलत लगेगा।
कार्यान्वयन पढ़ें और आपको यह गलत लगेगा।
प्रलेखन पढ़ें और आप इसे गलत करेंगे।
आम सम्मेलन का पालन करें और आप इसे गलत करेंगे।
इसे सही करें और यह कभी-कभी रनटाइम पर टूट जाएगा।
नाम आपको बताता है कि इसका उपयोग कैसे करना है।
स्पष्ट उपयोग गलत है।
संकलक चेतावनी देगा यदि आप इसे सही पाते हैं।
संकलक / लिंकर आपको इसे सही नहीं करने देगा।
सही होना असंभव है।

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

— JensG
स्रोत

0

आम आदमी के शब्दों में:

अमूर्त दृष्टिकोण के आसपास निर्मित कंक्रीट तरीकों की अनुमति देने का लाभ है।
आसपास का दूसरा रास्ता सच नहीं है

— ट्यूलेंस कोर्डोवा
स्रोत

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

— 19

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

— रोमन सूसी

0

यदि आप SearchCriteriaविचार को थोड़ा बढ़ाते हैं , तो यह आपको लचीलापन प्रदान कर सकता है जैसे कि निर्माण AND, ORआदि मानदंड। यदि आपको ऐसी कार्यक्षमता की आवश्यकता है, तो यह बेहतर दृष्टिकोण होगा।

अन्यथा, इसे प्रयोज्य के लिए डिज़ाइन करें। जो लोग इसका उपयोग करते हैं उनके लिए एपीआई को आसान बनाएं। यदि आपके पास कुछ बुनियादी कार्य हैं, जिनकी अक्सर आवश्यकता होती है (जैसे किसी व्यक्ति के नाम से खोज), तो उन्हें सीधे प्रदान करें। यदि उन्नत उपयोगकर्ताओं को उन्नत खोजों की आवश्यकता है, तो वे अभी भी उपयोग कर सकते हैं SearchCriteria।

— Uooo
स्रोत

0

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

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

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

— stonemetal
स्रोत

एपीआई डिजाइन: ठोस बनाम अमूर्त दृष्टिकोण - सर्वोत्तम प्रथाओं?