एक बच्चे के उद्देश्य और सभी माता-पिता के सभी बच्चों को प्राप्त करने के लिए एपीआई एंडपॉइंट कैसे डिज़ाइन करें?

Question

उदाहरण के लिए मेरे पास संस्थाएं हैं: ग्राहक, रिपोर्ट। क्लाइंट के पास कई रिपोर्ट हो सकती हैं और मुझे लगता है कि एकल रिपोर्ट प्रबंधन के लिए समापन बिंदु इस तरह से होना चाहिए:

/clients/{client_id}/reports/{report_id}

एक ग्राहक की सभी रिपोर्टों के लिए जैसा कि उम्मीद की जाती है:

/clients/{client_id}/reports

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

मेरा दृष्टिकोण:

1. (मैंने इसे कुछ google api में देखा) उपयोग "-" इसके बजाय और इसे "सभी" के रूप में पार्स करें

/clients/-/reports

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

2. सभी रिपोर्टों के लिए एक अलग समापन बिंदु बनाएं:

/reports

लेकिन ग्राहक की रिपोर्ट प्राप्त करने के लिए यह अभी भी है:

/clients/{client_id}/reports

3. रिफैक्टर एंडपॉइंट को "क्लाइंट" बनाने के लिए अभिभावक नहीं, बल्कि एक फ़िल्टर पैरामीटर:

/reports?client={client_id} - एक ग्राहक की रिपोर्ट

/reports - सभी क्लाइंट की रिपोर्ट

किसी विशिष्ट क्लाइंट के लिए एक रिपोर्ट पोस्ट करने के लिए एक नया समापन बिंदु जोड़ने के मामले में, यह बदसूरत लग सकता है, क्योंकि यह URL में एक पैरामीटर के साथ एक POST-request होगा।

क्या विचारों का कोई और सुझाव है?

Comments

आपकी रुचि का सवाल

— Laiv

Answer 1

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

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

इसलिए अभिव्यंजना से तीन विकल्पों की जाँच करें।

# 1 "-" संकेतन

यह एक उज्ज्वल विचार है। यह हमें उस स्थिति को व्यक्त करने की अनुमति देता है जो सभी reportsसंबंधित हैंclients । यह रिपोर्ट के एक विशेष सेट ( clientsसीमा के भीतर स्थित ) के लिए "क्वेरी" को कम कर रहा है ।

यह हर समय पदानुक्रम (संबंधित) की धारणा रखता है, इसलिए यदि reportsविभिन्न स्थानों में पाया जा सकता है , तो यह अंकन एक बड़ा सौदा करता है। उदाहरण के लिए:

• सभी रिपोर्ट जो ग्राहकों की हैं /clients/-/reports
• सभी रिपोर्ट जो विभागों की हैं /departments/-/reports
• सभी रिपोर्ट जो कर्मचारियों की हैं /employees/-/reports

हालाँकि, सिस्टम में उपलब्ध सभी रिपोर्टों को पुनः प्राप्त करने के लिए, पदानुक्रम को रखने से अगले विकल्प पर कोई मूल्यवान लाभ नहीं मिलता है।

# 2 विभिन्न यू.आर.आई.

यदि हमें सभी उपलब्ध रिपोर्टों को पुनः प्राप्त करने के समय सीमाओं / संदर्भों / पदानुक्रम को व्यक्त करने की आवश्यकता नहीं है , तो यह दृष्टिकोण मुझे अधिक उचित लगता है।

नया यूआरआई ( /reports) एक रिपोर्ट प्रबंधन के लिए भी संभावना छोड़ देता है । हालाँकि, यदि हम इसे आवश्यक नहीं मानते हैं, तो हमें इसे पूरी तरह से सहायता प्रदान करने की आवश्यकता नहीं है। उदाहरण के लिए, आपने बताया है Make a separate endpoint just for all the reports। यह ठीक है, आपको केवल लागू करना होगा GETऔर शायद क्वेरी के लिए कुछ फ़िल्टर करना होगा और यही है।

ध्यान दें कि आप अभी भी ऐसा कर सकते हैं /reports?client={client_id}। एक ही संसाधन के लिए अलग-अलग URI होना ठीक है। मेरे द्वारा पढ़े गए कुछ लेख इस मजबूती को कहते हैं ।

# 3 पदानुक्रम को वापस लाना

मुझे लगता है कि यह दृष्टिकोण आपकी अपेक्षाओं को पूरा नहीं करता है। इसके अलावा, मुझे लगता है, यह आपको अंततः शुरुआती बिंदु पर लाएगा।

निष्कर्ष

ध्यान दें कि # 1 और # 2 परस्पर अनन्य नहीं हैं। हम दोनों को लागू कर सकते हैं। वास्तविक स्थिति को देखते हुए और ओपी के परिसर के अनुसार, मैं केवल # 2 को लागू करूंगा।

---

^{1: यह /clients/-/reportsमेरे हिसाब से बराबर है}

Answer 2

Google का API डिज़ाइन पैटर्न इस परिदृश्य में '-' का उपयोग करने का सुझाव देता है।

GET /clients/-/reports

स्रोत:

https://cloud.google.com/apis/design/design_patterns#list_sub-collections

Comments

मेरे लिए सर्वशक्तिमान Google से असहमत होना दूर है, लेकिन मुझे लगता है कि मैं कुछ पसंद करूंगा /client/{client_id}/report/{report_id}और/clients/report/{report_id}

— रॉबर्ट हार्वे

@RobertHarvey सिर्फ क्यों नहीं /reports?

— Laiv

@ लीव: यह सभी रिपोर्टों का अर्थ होगा। अपने पृष्ठ को ताज़ा करें; मैंने निंजा एडिट किया।

— रॉबर्ट हार्वे

@RobertHarvey मेरा मतलब है, 2 अलग-अलग समापन बिंदु /clients...और क्यों नहीं /reports।

— Laiv

@ लिव: ठीक है, लेकिन यह सवाल उठता है कि "मुझे अनुरोध बॉडी में कौन से पैरामीटर लगाने चाहिए?"

— रॉबर्ट हार्वे