REST API के लिए क्या कोई नामकरण कन्वेंशन दिशा-निर्देश हैं? [बन्द है]

212

बंद हो गया । यह सवाल राय आधारित है । यह वर्तमान में उत्तर स्वीकार नहीं कर रहा है।

इस प्रश्न को सुधारना चाहते हैं? प्रश्न को अपडेट करें ताकि इस पोस्ट को संपादित करके तथ्यों और उद्धरणों के साथ उत्तर दिया जा सके ।

2 साल पहले बंद हुआ ।

इस प्रश्न को सुधारें

REST API का निर्माण करते समय, क्या API के भीतर सम्मेलनों के नामकरण के लिए कोई दिशा-निर्देश या डिफैक्टो मानक हैं (उदाहरण: URL समापन पथ पथ, क्वेरिस्ट्रिंग पैरामीटर)? क्या ऊंट कैपल्स आदर्श हैं, या अंडरस्कोर? अन्य?

उदाहरण के लिए:

api.service.com/helloWorld/userId/x

या

api.service.com/hello_world/user_id/x

नोट: यह RESTful API डिज़ाइन का प्रश्न नहीं है, बल्कि नामांकित कन्वेंशन दिशा-निर्देशों का उपयोग करने के लिए अंतिम पथ घटकों और / या क्वेरी स्ट्रिंग मापदंडों का उपयोग करने के लिए है।

किसी भी दिशा निर्देशों की सराहना की जाएगी।

api rest naming-conventions

— jnorris
स्रोत

150

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

तो आपका URL इस तरह दिखना चाहिए (जैसा कि आपने अनुरोध किया है डिजाइन की अनदेखी करना)

api.service.com/hello-world/user-id/x

— LiorH
स्रोत

187

RFC2616 के अनुसार केवल URL की योजना और होस्ट भाग केस-असंवेदनशील हैं। शेष URL, अर्थात पथ और क्वेरी SHOULD संवेदनशील होना चाहिए। w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.2.3

— डारेल मिलर

10

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

— LiorH

18

@ LiorH: आपको क्या लगता है कि यह "कोई मतलब नहीं" मामले के प्रति संवेदनशील है? अन्य संदर्भों के बहुत अच्छे प्रभाव के प्रति संवेदनशील हैं। वहाँ कुछ वेब सेवाओं (जैसे अमेज़न S3) कर रहे हैं करना यूआरएल अंतिमबिंदुओं के लिए मामला संवेदनशीलता लागू करने, और मुझे लगता है कि यह बिल्कुल उचित है।

— हांक

6

@Dennis Windows सर्वर फ़ाइल सिस्टम, डिफ़ॉल्ट रूप से केस असंवेदी होती हैं जब तक कि मैं अत्यंत कष्ट गलत कर रहा हूँ technet.microsoft.com/en-us/library/cc725747.aspx

— samspot

5

@samspot अच्छा एक! मैंने सोचा कि जब वे सर्वर बनाए तो संवेदनशील फ़ाइल नामों के लिए विंडोज़ सीधे चले गए थे। वाह, वे अभी भी अपने रास्ते को धक्का दे रहे थे जब तक वे कर सकते थे, अर्थात "1 माइक्रो सॉफ्ट वे"। ;-)

— डेनिस

87

ड्रॉपबॉक्स , ट्विटर , गूगल वेब सर्विसेज और फेसबुक के लिए REST API सभी अंडरस्कोर का उपयोग करता है।

— jz1108
स्रोत

24

इसका एक दुष्परिणाम यह है कि गूगल के सर्च इंडेक्स में अंडरस्कोर वाले are शब्दों ’को पूरा रखा जाता है। अलग-अलग शब्दों में टूटे हुए हैं।

— डेनिस

उदाहरण: dev.twitter.com/docs/api/1.1

— mike kozelsky

11

जबकि Google मैप्स एपीआई अंडरस्कोर का उपयोग करता है, Google स्टाइल गाइड को कैमल केस की आवश्यकता होती है। Google+ API और कस्टम खोज API , दूसरों के बीच, ऊंट मामले का उपयोग करें।

— बेंजामिन

2

फिर भी वे अभी भी '-' का उपयोग उन विभाजक के रूप में करते हैं जो urls करते हैं: P Developers.google.com/custom-search/json-api/v1/reference/cse/… Developers.google.com/+/best-practices dev.twitter। com / ओवरव्यू / केस-स्टडीज दूसरी ओर वे क्वेरी मापदंडों में कैमलकेस का उपयोग करते हैं।

— मटियास

1

किसी को नहीं पता ...

— पियोट कुल

84

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

HelloWorldसंसाधनों का वास्तव में अच्छा वर्ग नहीं है। यह एक "बात" प्रतीत नहीं होती है। यह हो सकता है, लेकिन यह बहुत संज्ञा की तरह नहीं है। A greetingएक चीज है।

user-idएक संज्ञा हो सकती है कि आप ला रहे हैं। हालाँकि, यह संदेहास्पद है, कि आपके अनुरोध का परिणाम केवल user_id है। यह बहुत अधिक संभावना है कि अनुरोध का परिणाम एक उपयोगकर्ता है। इसलिए, userआप जिस संज्ञा को ला रहे हैं , वह संज्ञा है

www.example.com/greeting/user/x/

मेरी समझ मे आ रहा है। अपने REST अनुरोध को एक प्रकार की संज्ञा वाक्यांश बनाने पर ध्यान दें - एक पदानुक्रम (या वर्गीकरण, या निर्देशिका) के माध्यम से एक पथ। यदि संभव हो तो संज्ञा वाक्यांशों से बचते हुए, सरलतम संज्ञाओं का उपयोग करें।

आमतौर पर, यौगिक संज्ञा वाक्यांशों का मतलब आमतौर पर आपकी पदानुक्रम में एक और कदम होता है। तो अगर आप की जरूरत नहीं है /hello-world/user/और /hello-universe/user/। आपके पास /hello/world/user/और hello/universe/user/। या संभवतः /world/hello/user/और /universe/hello/user/।

बिंदु संसाधनों के बीच एक नेविगेशन मार्ग प्रदान करना है।

— S.Lott
स्रोत

4

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

— 18

1

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

— aehlke

30

'UserId' पूरी तरह से गलत दृष्टिकोण है। Verb (HTTP मेथड्स) और नॉन अप्रोच, रॉय फील्डिंग द रेस्ट आर्किटेक्चर के लिए क्या है । संज्ञा या तो हैं:

एक संग्रह चीजों में से
एक बात

एक अच्छा नामकरण सम्मेलन है:

[POST or Create](To the *collection*)
sub.domain.tld/class_name.{media_type} 

[GET or Read](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[PUT or Update](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[DELETE](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[GET or Search](of a *collection*, FRIENDLY URL)
sub.domain.tld/class_name.{media_type}/{var}/{value}/{more-var-value-pairs}

[GET or Search](of a *collection*, Normal URL)
sub.domain.tld/class_name.{media_type}?var=value&more-var-value-pairs

जहाँ {media_type} एक है: json, xml, rss, pdf, png, html भी।

अंत में 's' जोड़कर संग्रह को अलग करना संभव है, जैसे:

'users.json' *collection of things*
'user/id_value.json' *single thing*

लेकिन इसका मतलब है कि आपको इस बात का ध्यान रखना होगा कि आपने 'एस' कहां रखा है और आपने कहां नहीं लगाया है। साथ ही आधा ग्रह (शुरुआत के लिए एशियाई) स्पष्ट plurals के बिना भाषा बोलता है ताकि URL उनके लिए कम अनुकूल हो।

— डेनिस
स्रोत

{Var} का क्या अर्थ है? अगर मैं एक उपयोगकर्ता को नाम से खोजता हूं जो उदाहरण के लिए होगा ... / उपयोगकर्ता / उपयोगकर्ता नाम / tomsawyer?

— हंस-पीटर स्टॉर्र

1

यदि आपके पास x, y, z नाम के तीन चर (var) हैं, तो आप URL की तरह दिखेंगे

— डेनिस

@hstoerr बस यह सुनिश्चित करने के लिए कि मैं स्पष्ट था, अधिकांश स्क्रिप्ट भाषाएं कुछ प्रकार के 'घुंघराले ब्रैकेट चर प्रतिस्थापन' का उपयोग करती हैं। तो {var} यह दर्शाता है कि कुछ चर (यह नाम) वहां रहता है, और इसलिए निम्न {value} वह स्थान है, जहां इससे पहले {var} का मान है। उदाहरण: sub.domain.tld / script / {var} / {value} .json [www.yelp.com/food_reviews/review_aactions_higher_than/4.json] भोजन reveiws दिखाने के लिए yelp.com से json परिणाम प्राप्त करने की कोशिश कर रहा होगा। मान 4 से अधिक है

— डेनिस

अंतरराष्ट्रीय स्तर पर सोचने के लिए मेरी राय और कुदोस में यह सबसे अच्छा जवाब है।

— बीलर

14

REST का URI नामकरण सम्मेलनों से कोई संबंध नहीं है। यदि आप इन सम्मेलनों को अपने एपीआई के भाग के रूप में, केवल हाइपरटेक्स्ट के माध्यम से, आउट-ऑफ-बैंड के रूप में शामिल करते हैं, तो आपका एपीआई रेस्टफुल नहीं है।

अधिक जानकारी के लिए, http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven देखें

— aehlke
स्रोत

44

इसे आराम दें ... अच्छा दिखने वाला URL होना अभी भी अच्छा है।

— HDave

1

@ हवे के साथ सहमत होना, REST की भावना में बहुत अधिक URL हैं जो आसानी से समझे जा सकते हैं। आप URL के साथ काम कर रहे हैं, आप क्यों नहीं चाहेंगे कि वे आपके कोड में चर और पैरामीटर नामों के रूप में आसानी से समझे जा सकें?

— मैहेमॉफ

4

@ ओमहॉफ सॉरी, यह मुझे सुपर पांडित्य है। लेकिन आपके URL जो दिखते हैं, उनका REST से कोई लेना-देना नहीं है। इसका मतलब यह नहीं है कि वे करने के लिए एक अच्छी बात नहीं कर रहे हैं, वे सिर्फ वही है जो REST का वर्णन करता है। यह कहना भ्रामक है कि REST इस तरह से URL को संरचित करने के बारे में है, क्योंकि यह RPC API को REST के रूप में वर्णित करने वाले लोगों की ओर ले जाता है क्योंकि उनके पास पठनीय / संरचित URL होते हैं।

— aehlke

5

सारांश में, अच्छे दिखने वाले URL बहुत अच्छे हैं और हर किसी के पास होना चाहिए। हालांकि इसका REST से कोई लेना-देना नहीं है।

— aehlke

1

@aehlke इसे साफ़ करने के लिए धन्यवाद। बाकी URL संरचनाओं के बारे में नहीं है। मुझे समझ नहीं आता कि लोगों को समझना इतना कठिन क्यों है।

— user1431072

9

डोमेन नाम केस संवेदी नहीं हैं लेकिन बाकी यूआरआई निश्चित रूप से हो सकते हैं। यूआरआई के मामले संवेदनशील नहीं होना एक बड़ी गलती है।

6

मेरे पास http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html पर दिशानिर्देशों की एक सूची है, जिनका हमने ठेस में उपयोग किया है। दिशानिर्देश हमेशा बहस योग्य होते हैं ... मुझे लगता है कि कभी-कभी चीजें सही होने से ज्यादा महत्वपूर्ण है (अगर ऐसी कोई बात है)।

— रॉबर्ट मॉर्शेल
स्रोत

2

मुझे नहीं लगता कि ऊंट का मामला उस उदाहरण में मुद्दा है, लेकिन मैं कल्पना करता हूं कि उपरोक्त के लिए एक अधिक प्रतिष्ठित नामकरण सम्मेलन होगा:

api.service.com/helloWorld/userId/x

बल्कि तब userId को एक क्वेरी पैरामीटर (जो पूरी तरह से कानूनी है) बनाने से मेरा उदाहरण उस संसाधन, IMO, एक अधिक प्रतिष्ठित तरीके को दर्शाता है।

— Gandalf
स्रोत

यह RESTful API डिज़ाइन का प्रश्न नहीं है, बल्कि नामांकित कन्वेंशन दिशा-निर्देशों का उपयोग करने के लिए अंतिम पथ घटकों और / या क्वेरी स्ट्रिंग मापदंडों के लिए उपयोग किया जाता है। आपके उदाहरण में, क्या रास्ते के घटक ऊंट की टोपी में होने चाहिए, जैसा आपने इस्तेमाल किया है, या अंडरस्कोर?

— जॉनरिस

वैसे चूंकि REST में आपके URL आपके इंटरफेस हैं, तो यह एक तरह का एपीआई प्रश्न है। जबकि मुझे नहीं लगता कि आपके उदाहरण के लिए कोई दिशानिर्देश हैं, मैं व्यक्तिगत रूप से ऊंट मामले के साथ जाऊंगा।

— गंडालफ

आपको उन संसाधनों के लिए क्वेरी पैरामीटर का उपयोग नहीं करना चाहिए जिन्हें आप HTTP स्टैक के किसी भी स्तर पर कैश करना चाहते हैं।

— ऐहलके

@aehlke सटीक विपरीत भी सही है। यदि आप क्वेरी पैरामीटरों को कैश नहीं करना चाहते हैं, तो पैरामीटर के लिए GET शैली का उपयोग करें, ~ या ~ किसी भी चीज के लिए एंटी कैशिंग हेडर को संशोधित / सम्मिलित करने के लिए DARN SURE करें, जिसे आप कैश नहीं चाहते हैं। इसके अलावा, thre कुछ हेडर है जो ऑब्जेक्ट / पेज रेटुरेंड का हैश है, इसका उपयोग उन चीजों के परिवर्तनों को इंगित करने के लिए करें जिन्हें आप कैश्ड चाहते हैं, लेकिन एडिट होने पर अपडेट किया जाता है।

— डेनिस

@aehlke को कैशिंग के बारे में पता चला और इसे जोड़ रहा हूँ। मुझे याद है कि एक कोडकैम्प प्रस्तुति जहां एक स्पीडअप इन सभी हेडर को कर रहा था, और तब फ़ाइल का नाम और उसके सभी संदर्भ बदल रहा था जब बोरर्स और परदे के पीछे पाने के लिए सामग्री बदल गई है ताकि एक लंबे कैश के बाद एक नया संस्करण सर्वर किया जा सके। सेट। यहाँ सभी गोरी विवरण हैं: Developers.google.com/speed/docs/best-practices/caching

— डेनिस

2

यदि आप Oauth2 के साथ अपने ग्राहकों को प्रमाणित करते हैं, तो मुझे लगता है कि आपको अपने कम से कम दो पैरामीटर नामों के लिए अंडरस्कोर की आवश्यकता होगी:

ग्राहक ID
client_secret

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

देखें: https://tools.ietf.org/html/rfc6749

— माइकल
स्रोत

0

मैं कहूंगा कि REST URL में यथासंभव कुछ विशेष वर्णों का उपयोग करना बेहतर होगा। आरईएसटी के लाभों में से एक यह है कि यह एक सेवा को पढ़ने के लिए आसान "इंटरफ़ेस" बनाता है। ऊंट का मामला या पास्कल मामला संभवतः संसाधन नामों (उपयोगकर्ताओं या उपयोगकर्ताओं) के लिए अच्छा है। मुझे नहीं लगता कि वास्तव में REST के आसपास कोई कठोर मानक हैं।

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

http://api.example.com/HelloWorld/Users/12345/Order/3/etc

— एंडी व्हाइट
स्रोत