क्या यह 3 पार्टी संदर्भ आईडी के गुणों के रूप में एपीआई ऑब्जेक्ट परिभाषा के लिए बुरा अभ्यास है?

Question

ऐशे ही:

Campaign:
type: object
properties:
  id: 
    type: string
    description: "A GUID identifier"
  referenceId:
    type: string
    description: "A consumers identifier they have used to map their own systems logic to this object."
  name:
    type: string
    description: "'Great Campaign 2017' as an example"

मैं संदर्भ के बारे में चिंतित हूँ ।

सिस्टम डोमेन एक ऐसा प्लेटफ़ॉर्म है जो डेटा निर्यात और विभिन्न प्रारूपों (xml, एक्सेल) के आयात के माध्यम से 3 तरह से 3 पार्टियों के साथ एकीकृत है। यह पर्याप्त परिपक्व है कि तीसरे पक्ष को एक एपीआई के माध्यम से हमारे सिस्टम के साथ एकीकृत करने की अनुमति दी जाए और इस एपीआई का डिजाइन इस प्रश्न का संकेत देता है।

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

हमारे सिस्टम में इस तरह के 3 पार्टी संदर्भ क्षेत्रों के साथ अन्य ऑब्जेक्ट हैं और यह हमारे मौजूदा उपभोक्ताओं से अपेक्षित है। हालाँकि, मुझे चिंता है कि यह हम पर मैपिंग का बोझ डालता है और हमें नहीं पता कि यह referenceId क्या है (नंबर, टेक्स्ट, json?) और यह नए उपभोक्ताओं के लिए API में एक और भ्रामक संपत्ति जोड़ता है।

क्या किसी API के लिए सार्वजनिक ऑब्जेक्ट परिभाषाओं में 3rd पार्टी संदर्भ आईडी फ़ील्ड की अनुमति देने के लिए इसे बुरा अभ्यास या खराब डिज़ाइन माना जाता है?

Answer 1

ये कोई समस्या नहीं है; यह एक आवश्यकता है। ग्राहक प्रणालियों के साथ एकीकरण के लिए इस क्षेत्र की कमी समस्याग्रस्त होगी।

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

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

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

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

Comments

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

— jezpez

Answer 2

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

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

लेकिन फिर, अगर यह आपके और उनके बीच के अनुबंध का हिस्सा है तो आपको अपने सौदेबाजी का हिस्सा रखना होगा और उस अपारदर्शी संपत्ति को प्रदान करना होगा।

Answer 3

3 पार्टी के संदर्भ एक अच्छा विचार है जहां किसी भी विशेष डेटा का स्वामित्व तीसरे पक्ष के पास है, और आप सिर्फ एक संरक्षक हैं।

यह लिखने / अपडेट करने के लिए idempotency के लिए एक तंत्र स्थापित करने के लिए भी बेहद मददगार है।

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

लचीलेपन के लिए, संदर्भों के लिए मनमाना तार होना विशिष्ट है।

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

सभी आंतरिक संदर्भ आंतरिक पहचानकर्ता का उपयोग करेंगे। यह REST दुनिया के साथ भी बेहतर बैठता है, जो URL के साथ id के इन-लाइन लागू करने जैसे काम कर सकता है, अगला बिंदु देखें।

बाहरी API पर, पहचानकर्ता का उपयोग करके प्रश्नों की अनुमति दें। आप क्वेरी पैरामीटर का उपयोग करके इसे एक अलग समापन बिंदु, या (REST दुनिया में) कर सकते हैं।

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

असफल होना कि आप ऑपरेशन लेनदेन आईडी / संदेश आईडी का उपयोग कर सकते हैं, लेकिन यह प्रश्न के दायरे से बाहर है।

Comments

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

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

— बादशाह