खराब एपीआई कैसे लिखें

कोड को इस तरह लिखें जैसे यह एक हिंसक मनोरोगी के साथ होगा जो जानता है कि आप कहाँ रहते हैं।

सभी को नमस्कार!

मैं ऑनलाइन होटल आरक्षण सेवा Ostrovok.ru में एकीकरण विकास टीम की टीम लीड के रूप में काम करता हूं और आज मैं विभिन्न एपीआई के साथ अपने अनुभव को साझा करना चाहता हूं।

बाहरी प्रदाताओं के साथ काम करने वाली प्रणाली के एक डेवलपर के रूप में, मैं अक्सर विभिन्न एपीआई में आता हूं - सबसे अधिक बार यह SOAP / REST या उनके समान कुछ है। हालांकि, उनमें से कई के साथ काम करने से यह आभास होता है कि वे लिखे गए थे, न कि तकनीकी नियमों या सामान्य ज्ञान द्वारा निर्देशित - जैसे कि ग्रिगरी ओस्टर की पुस्तक "बैड एडवाइस"। इस लेख में मैं "खराब सलाह" की शैली में ऐसे मामलों का वर्णन करने और एक्सएमएल से संबंधित उदाहरणों पर विचार करने की कोशिश करूंगा। टिप्पणियाँ और चर्चा का स्वागत है।

ऐतिहासिक पृष्ठभूमि

SOAP (अंग्रेजी से। सरल ऑब्जेक्ट एक्सेस प्रोटोकॉल - वस्तुओं तक पहुंचने के लिए एक सरल प्रोटोकॉल) - एक वितरित कंप्यूटिंग वातावरण में संरचित संदेशों के आदान-प्रदान के लिए एक प्रोटोकॉल। SOAP मूल रूप से दूरस्थ प्रक्रिया कॉल (RPC) को लागू करने के लिए बनाया गया था। अब प्रोटोकॉल का उपयोग एक्सएमएल प्रारूप में मनमाने संदेशों के आदान-प्रदान के लिए किया जाता है, न कि केवल कॉलिंग प्रक्रियाओं के लिए।

उदाहरणों पर जाएं

1. url को xml पास करना

एपीआई उपयोगकर्ता सबसे ज्यादा क्या चाहते हैं? बेशक, सादगी, विश्वसनीयता और संक्षिप्तता। तो चलिए रिक्वेस्ट बॉडी को नहीं पढ़ते हैं, लेकिन अनुरोध पथ के पैरामीटर के रूप में XML को url-encoded जानकारी के रूप में स्वीकार करते हैं! क्या बेहतर हो सकता है:

http://exapmple.com/xml/form.jsp?RequestName%3DHotelRequest2%26XML%3D%3C%3Fxml%2Bversion%3D%221.0%22%2Bencoding%3D%22UTF-8%22%3F%3E%0A%3CHotelRequest2%2BBuyerId%3D%22test%22%2BUserId%3D%22test%22%2BPassword%3D%22test%22%2BLanguage%3D%22en%22%2BHotel%3D%22-100%22%2BProductCode%3D%221--%22%2BArrivalDate%3D%2223.12.2018%22%2BDepartureDate%3D%2224.12.2018%22%2BArrivalTime%3D%22%22%2BDepartureTime%3D%22%22%2BCurrency%3D%222%22%2BWhereToPay%3D%223%22%2BNumberOfGuests%3D%220%22%2BNumberOfExtraBedsAdult%3D%220%22%2BNumberOfExtraBedsChild%3D%220%22%2BNumberOfExtraBedsInfant%3D%220%22%2B%2F%3E 

सब कुछ सरल हो जाता है, और क्वेरी से कुछ शरीर को घटाने की आवश्यकता नहीं है - आप कभी नहीं जानते कि इसके साथ क्या समस्याएं हो सकती हैं।

2. डेटा ऑब्जेक्ट्स के अत्यधिक नेस्टिंग के माध्यम से सूचना स्थानांतरण

आइए विचार करें कि उत्तरों में जानकारी को यथासंभव कठिन कैसे बनाया जाए? चलो नेस्टेड संरचनाओं का उपयोग करें, और यहां तक ​​कि विभिन्न स्वरूपों में भी! जल्दी से नहीं कहा -

 <Request> <InnerRequest> <RQ>[{"someInfo":"base64Data"}] </RQ> </InnerRequest> </Request> 

वास्तव में, शीर्ष-स्तरीय xml, इसके अंदर एक और xml है, और इसके अंदर json है, जिसमें डेटा को बेस 64 में प्रस्तुत किया गया है, और फिर से इसमें json, और इसमें पहले से ही हमारे पास मौजूद जानकारी होगी! एक महान समाधान, लगभग एक अंडा में छिपे हुए कोशी की मौत के बारे में एक परी कथा की तरह।

3. ऐसी जानकारी जोड़ना जो अनुरोध डेटा से संबंधित नहीं है और डेटा प्रारूप में मान्य नहीं है

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

 XML= <Request> ... </Request> 

ऐसे सरल तरीके से, हम हमेशा जानेंगे कि हमें XML प्रारूप में अनुरोध प्राप्त हुआ है।

4. बिना आवश्यकता के डेटा का दोहराव

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

 <Response> <Obj Info="Important"> <ObjSetting Info="Important"/> <Name>SomeName</Name> <Info>Important</Info> </Obj> </Response> 

उसके बाद, अंत उपयोगकर्ता निश्चित रूप से जानकारी फ़ील्ड पर ध्यान देगा।

5. एक ही प्रकार के मापदंडों को व्यक्तिगत रूप से पारित करना, एक सरणी नहीं

हम जिन होटलों में खोज करने के लिए उपयोग करते हैं, उनमें से एक में मेहमानों की उम्र का संकेत देने वाले क्षेत्र हैं। इस जानकारी को व्यक्त करने के लिए किस प्रस्तुति प्रारूप का उपयोग किया जाता है? प्रारूप को इस तरह से होने दें: प्रत्येक आयु एक अलग अनिवार्य XML टैग होगी, और हम मान 0 को इस पैरामीटर की अनुपस्थिति के रूप में मानेंगे।

 <Request> <Age1>20</Age> <Age2>20</Age> <Age3>0</Age> <Age4>0</Age> </Request> 

6. एपीआई कॉल चेन के हिस्से के रूप में पिछले अनुरोधों से जानकारी अग्रेषित करना

यह हमारे एपीआई की सुरक्षा के बारे में सोचने का समय है। हम यह कैसे समझते हैं कि उपयोगकर्ता हमारे पिछले उत्तरों से जानकारी प्राप्त करता है? उसे हमें अपना जवाब जरूर भेजें!

 <Request> <RequestInfo/> <PreviosResp> ... </PreviosResp> </Request> 

7. किसी त्रुटि के मार्कर का उपयोग न करें, जैसे त्रुटि टैग या http कोड

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

 <Response> <ImportantInfo/> </Response> 

- 200 ओके के रिस्पांस कोड के साथ।

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