आरईएसटी एपीआई

Question

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

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

GET /persons/12 

{ 
    "name": Morgan 
    "ssn": "840212-3312" 
} 

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

GET /persons/840212-3321 

{ 
    "name": Morgan 
    "id": "12" 
} 

तो सवाल यह है: मैं पहली बार दृष्टिकोण के साथ जाना चाहिए, और कुछ कार्यान्वयन सिर दर्द जहां एसएसएन बदल सकते हैं से बचें। और शायद कुछ सहायक विधि प्रदान करें जो एसएसएन से आईडी में परिवर्तित हो जाती है?

या दूसरे दृष्टिकोण के साथ जाएं। एक अधिक जानकारीपूर्ण एपीआई प्रदान करना। हालांकि कुछ लोगों के साथ सौदा करने के लिए अजीब अजीबता नहीं है, जहां एसएसएन परिवर्तनों के कारण यूआरएल: बदल सकता है?

Answer 1

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

मैं एक उपयोगकर्ता खाते संसाधन है और दोनों यूआरआई के माध्यम से उपयोग की अनुमति:

/users/12 

और

/users/morgan 

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

मेरे सिस्टम पर किसी अन्य संसाधन के दो अद्वितीय फ़ील्ड नहीं हैं, इसलिए आईडी, /jobs/123, /quotations/456 द्वारा संदर्भित किया जाता है।

आप देख सकते हैं, मैं बहुवचन यूआरआई क्षेत्रों ;-)
मैं "नौकरी 123" के बारे में सोच, पसंद करते हैं "नौकरियों" संग्रह से होने के रूप में तो यह एक "नौकरियों" संसाधन के लिए तार्किक लगता है के लिए subresources साथ प्रत्येक नौकरी

आप खोज करने के बदले एक अलग /search/ क्षेत्र की आवश्यकता नहीं है, मुझे लगता है कि यह सीधे संग्रह संसाधन के लिए आपके खोज मानदंडों को लागू करने के क्लीनर होगा:

/people?ssn=123456-7890 (people with SSN matching/containing "123456-7890") 
/people?name=morgan  (people who's name is/contains "Morgan") 

मैं कुछ इसी तरह की है, लेकिन केवल का उपयोग एक फिल्टर के रूप पहले अक्षर: एफ के साथ शुरुआत

/sites?alpha=f 

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

Answer 2

किसी को अपने संसाधन यूआरएल के बारे में सोचने के लिए समय निकालने के लिए अच्छा लगता है!

मैं एक उपयोगकर्ता को संसाधन प्रदान करने के लिए अद्वितीय आईडी के साथ एक यूआरएल बनाउंगा। जैसा:

http://api.mysite.com/person/12/ 

कहाँ 12 अपने अद्वितीय आईडी है। ध्यान दें कि मैं भी विलक्षण 'व्यक्ति' पसंद करते हैं ....

परवाह किए बिना, यूआरएल लौटना चाहिए:

{ 
    "ssn": "840212-3312" 
    "name": "Morgan" 
    "id": "12" 
} 

हालांकि, मैं भी एक सामान्य खोज URL है कि उपयोगकर्ताओं को मेल खाने वाले की सूची लौटाता बन जाएगा पैरामीटर (या तो एक जेसन सरणी या जो भी प्रारूप आपको चाहिए)। के रूप में इस तरह पैरामीटर प्राप्त आप खोज पैरामीटर निर्दिष्ट कर सकते हैं:

http://api.mysite.com/person/search/?ssn=840212-3312 

या

http://api.mysite.com/person/search/?name=Morgan 

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

[{ 
    "ssn": "840212-3312" 
    "name": "Morgan" 
    "id": "12" 
}] 

इस खोज को बाद में अन्य खोज मानदंडों के लिए बढ़ाया जा सकता है। आप खोज यूआरएल के माध्यम से केवल अनन्य आईडी को वापस कर सकते हैं - जब आप इसे खोज से प्राप्त कर लेते हैं तो आप अनन्य आईडी यूआरएल के लिए हमेशा अनुरोध कर सकते हैं ...

Answer 3

मैं सुझाव दूंगा कि आप न तो इसका उपयोग करें। संसाधन आईडी उत्पन्न करें जो आपके एपीआई के एक उपयोगकर्ता और अन्य सभी संसाधनों (अन्य उपयोगकर्ताओं के संसाधनों सहित) दोनों के लिए अद्वितीय हैं।

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

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

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