JSON API - हम विनिर्देश के अनुसार काम करते हैं

हाल ही में, वेब विकास को विभाजित किया गया है। अब हम सभी पूर्ण-स्टैक प्रोग्रामर नहीं हैं - हम फ्रंट-एंड और बैक-एंड हैं। और इसके बारे में सबसे कठिन बात, जैसा कि कहीं और है, बातचीत और एकीकरण की समस्या है।

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

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



आइए दूर से शुरू करते हैं - जिस समस्या को हम हल कर रहे हैं।

बहुत समय पहले, 1959 में, सिरिल पार्किंसन (बीमारी से भ्रमित नहीं होने के लिए, वह एक लेखक और एक आर्थिक व्यक्ति है) कई दिलचस्प कानूनों के साथ आया था। उदाहरण के लिए, आय आदि से खर्च बढ़ता है। उनमें से एक को कानून का अधिकार कहा जाता है:

मद पर चर्चा करने में लगने वाला समय विचार की गई राशि के व्युत्क्रमानुपाती होता है।

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

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

यह शब्द डेनिश डेवलपर Poul-Henning Kamp द्वारा तैयार किया गया था, जो FreeBSD के निर्माण में शामिल था। डिजाइन प्रक्रिया के दौरान, टीम ने यह चर्चा करने में बहुत लंबा समय बिताया कि नींद समारोह कैसे काम करना चाहिए। यह पौल-हेनिंग काम्प के एक पत्र का उद्धरण है (विकास तब ई-मेल पत्राचार में किया गया था):

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

इस पत्र में, वे कहते हैं कि बहुत अधिक महत्वपूर्ण अनसुलझे समस्याएँ हैं: "चलो साइकिल शेड के साथ सौदा न करें, हम इसके बारे में कुछ करेंगे और आगे बढ़ेंगे!"

इसलिए 1999 में पुले-हेनिंग काम्प ने अंग्रेजी भाषा के साहित्य में बिकेश्ड शब्द की शुरुआत की, जिसे फिर से लिखा जा सकता है:

कोड में परिवर्तन से उत्पन्न शोर की मात्रा परिवर्तन की जटिलता के विपरीत आनुपातिक है।

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

आपको क्या लगता है कि यह अधिक महत्वपूर्ण है: हम बैकएंड और फ्रंटएंड या व्यावसायिक कार्यों के बीच कैसे संवाद करते हैं? हर कोई अलग तरह से सोचता है, लेकिन कोई भी ग्राहक, एक व्यक्ति जो आपसे पैसे लाने की उम्मीद करता है, वह कहेगा: "मुझे पहले से ही अपना व्यवसाय करो!" वह बिल्कुल परवाह नहीं करता है कि आप बैकएंड और फ्रंटेंड के बीच डेटा कैसे ट्रांसफर करते हैं। शायद वह यह भी नहीं जानता कि बैकएंड और फ्रंटएंड क्या है।

परिचय प्रस्तुत करने के लिए, मैं कहना चाहूंगा: एपीआई एक बाइक शेड है।


प्रस्तुति की कड़ी

स्पीकर के बारे में: एलेक्सी अवेदीव (एवीडीव) कंपनी न्यूरॉन.डिजिटल के लिए काम करती है, जो न्यूरॉन्स के साथ काम करती है और उनके लिए एक शांत दृश्य बनाती है। एलेक्स ओपनसोर्स पर भी ध्यान देता है और सभी को सलाह देता है। वह लंबे समय से विकास में लगे हुए थे - 2002 के बाद से, उन्होंने प्राचीन इंटरनेट पाया, जब कंप्यूटर बड़े थे, इंटरनेट छोटा था, और जेएस की कमी ने किसी को परेशान नहीं किया और सभी ने तालिकाओं पर वेबसाइटें बनाईं।

बाइक शेड से कैसे निपटें?

सम्मानित होने के बाद सिरिल पार्किंसन ने तुच्छता के कानून का पालन किया, वह बहुत चर्चा में था। यह पता चला है कि यहां साइकिल शेड के प्रभाव से आसानी से बचा जा सकता है:

1. सलाह मत सुनो। मुझे लगता है कि यह विचार बहुत ऐसा है - यदि आप सलाह नहीं सुनते हैं, तो आप इसे बहुत कुछ बना सकते हैं, खासकर प्रोग्रामिंग में, और खासकर यदि आप एक नौसिखिया डेवलपर हैं।
   
2. जैसा चाहो वैसा करो। "मैं एक कलाकार हूँ, मैं ऐसा देख रहा हूँ!" - बिना बिके हुए प्रभाव, आपको जो कुछ भी चाहिए वह किया जाता है, लेकिन आउटपुट पर बहुत अजीब चीजें दिखाई देती हैं। यह अक्सर फ्रीलांस में पाया जाता है। निश्चित रूप से आप उन कार्यों के लिए आए थे जिन्हें आपको अन्य डेवलपर्स के लिए पूरा करना था और जिसके कार्यान्वयन के कारण आप हतप्रभ थे।
   
3. क्या खुद से पूछना ज़रूरी है? यदि नहीं, तो आप बस इस पर चर्चा नहीं कर सकते, लेकिन यह व्यक्तिगत चेतना की बात है।
   
4. वस्तुनिष्ठ मापदंड का प्रयोग करें। मैं रिपोर्ट में इस बिंदु के बारे में बोलूंगा। साइकिल शेड के प्रभाव से बचने के लिए, आप उन मानदंडों का उपयोग कर सकते हैं जो उद्देश्यपूर्ण रूप से कहते हैं कि बेहतर है। वे मौजूद हैं।
   
5. जो आप सलाह नहीं सुनना चाहते, उसके बारे में बात न करें। हमारी कंपनी में, शुरुआत में बैकेंड डेवलपर्स परिचय हैं, इसलिए ऐसा होता है कि वे ऐसा कुछ करते हैं जिसके बारे में वे दूसरों को नहीं बताते हैं। परिणामस्वरूप, हम आश्चर्य में पड़ जाते हैं। यह तरीका काम करता है, लेकिन प्रोग्रामिंग में यह सबसे अच्छा विकल्प नहीं है।
   
6. यदि आप समस्या के बारे में परवाह नहीं करते हैं, तो आप इसे होलिवरोव की प्रक्रिया में आने वाले प्रस्तावित विकल्पों में से किसी को भी जाने या चुन सकते हैं ।
   

एंटी-बाइकेजिंग टूल

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

कल्पना कीजिए कि हमारे पास एक नौसिखिया बैकएंड डेवलपर है। वह हाल ही में कंपनी में आया था, और उसे एक छोटी सेवा डिजाइन करने का निर्देश दिया गया था, उदाहरण के लिए, एक ब्लॉग, जिसके लिए आपको एक REST प्रोटोकॉल लिखना होगा।

रॉय फील्डिंग, REST के लेखक

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

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

अन्य वास्तुकला आवश्यकताएँ

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

1. क्लाइंट-सर्वर मॉडल।
REST का सबसे महत्वपूर्ण सिद्धांत, यानी बैकएंड के साथ हमारी बातचीत। REST के अनुसार, बैकएंड एक सर्वर है, फ्रंट-एंड एक क्लाइंट है, और हम क्लाइंट-सर्वर प्रारूप में संवाद करते हैं। मोबाइल डिवाइस भी एक ग्राहक हैं। रेफ्रिजरेटर के लिए डेवलपर्स, अन्य सेवाओं के लिए - ग्राहक भाग भी विकसित करते हैं। RESTful API वह सर्वर है जिसे क्लाइंट एक्सेस करता है।

2. हालत की कमी।
सर्वर पर कोई राज्य नहीं होना चाहिए, अर्थात्, उत्तर के लिए आवश्यक सभी चीजें अनुरोध में आती हैं। जब कोई सत्र सर्वर पर संग्रहीत होता है, और इस सत्र के आधार पर विभिन्न उत्तर आते हैं, तो यह REST सिद्धांत का उल्लंघन है।

3. इंटरफ़ेस की एकरूपता।
यह प्रमुख अंतर्निहित सिद्धांतों में से एक है, जिस पर REST API का निर्माण किया जाना चाहिए। इसमें निम्नलिखित शामिल हैं:

• संसाधन पहचान यह है कि हमें एक URL कैसे बनाना चाहिए। REST पर, हम किसी प्रकार के संसाधन के लिए सर्वर की ओर मुड़ते हैं।
• प्रस्तुति के माध्यम से संसाधनों का हेरफेर। सर्वर हमें एक दृश्य देता है जो डेटाबेस में निहित है से अलग है। यदि आप MySQL या PostgreSQL में जानकारी संग्रहीत करते हैं तो इससे कोई फर्क नहीं पड़ता - हमारे पास एक दृश्य है।
• स्व-वर्णन करने वाले संदेश - अर्थात्, संदेश में आईडी है, लिंक जहां आप इस संदेश को फिर से प्राप्त कर सकते हैं - उन सभी को फिर से इस संसाधन के साथ काम करने की आवश्यकता है।
• हाइपरमीडिया एक संसाधन के साथ निम्नलिखित क्रियाओं की एक कड़ी है। यह मुझे लगता है कि एक भी REST API नहीं करता है, लेकिन यह रॉय फील्डिंग द्वारा वर्णित है।

3 और सिद्धांत हैं जो मैं उद्धृत नहीं करता क्योंकि वे मेरी कहानी के लिए महत्वपूर्ण नहीं हैं।

रेस्टफुल ब्लॉग

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



यह एक ऐसी साइट है जिस पर लेख हैं, आप उन पर टिप्पणी कर सकते हैं, लेख और टिप्पणियों में एक लेखक है - एक मानक कहानी। हमारे नौसिखिए बैकएंड डेवलपर इस ब्लॉग के लिए एक RESTful API करेंगे।

हम CRUD के आधार पर सभी ब्लॉग डेटा के साथ काम करते हैं।

किसी भी संसाधन को बनाना, पढ़ना, अपडेट करना और हटाना संभव होना चाहिए। आइए CRUD के सिद्धांत के आधार पर एक RESTful AP बनाने के लिए हमारे बैकएंड डेवलपर से पूछने की कोशिश करें। यही है, लेख बनाने के लिए तरीके लिखें, लेखों की एक सूची या एक लेख प्राप्त करें, अपडेट करें और हटाएं।

आइए देखें कि वह यह कैसे कर सकता है।


REST के सभी सिद्धांतों के बारे में यहाँ सब कुछ गलत है । सबसे दिलचस्प बात यह है कि यह काम करता है। मुझे वास्तव में एपीआई मिले जो कुछ इस तरह दिखते थे। ग्राहक के लिए यह एक साइकिल शेड है, डेवलपर्स के लिए यह चिल करने और बहस करने का एक अवसर है, और एक नौसिखिया डेवलपर के लिए यह एक विशाल, बहादुर नई दुनिया है, जिस पर वह हर बार ठोकर खाता है, गिरता है, अपना सिर मुंड़वाता है। उसे बार-बार इसे फिर से करना होगा।


यह एक REST विकल्प है। संसाधन पहचान के सिद्धांतों के आधार पर, हम संसाधनों के साथ काम करते हैं - लेखों के साथ और रॉय फील्डिंग द्वारा प्रस्तावित HTTP तरीकों का उपयोग करते हैं। वह अपने अगले काम में अपने पिछले काम का उपयोग करने में मदद नहीं कर सकता था।

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

हमारे नौसिखिए बैकएंड डेवलपर गिर गए, उन्होंने इसे उठाया और कहा: "सब कुछ क्रम में है, इसे ऐसे ही करो," और उसने ईमानदारी से इसे भुनाया। लेकिन तब वह कांटों के माध्यम से एक बड़ा लंबा रास्ता खोज लेगा।

यह इतना सही क्यों है?

• क्योंकि रॉय फील्डिंग ने ऐसा कहा था;
• क्योंकि यह REST है;
• क्योंकि ये वास्तु सिद्धांत हैं जिन पर हमारा पेशा आधारित है।

हालांकि, यह एक "साइकिल शेड" है, और पिछली विधि काम करेगी। कंप्यूटर ने REST से पहले संचार किया, और सब कुछ काम किया। लेकिन अब उद्योग में एक मानक दिखाई दिया है।

लेख को हटा दें

एक लेख को हटाने के उदाहरण पर विचार करें। मान लीजिए कि एक सामान्य, संसाधन विधि DELETE / लेख है, जो आईडी द्वारा लेख को हटा देता है। HTTP में हेडर हैं। एक्सेप्ट हेडर उस डेटा के प्रकार को स्वीकार करता है जिसे ग्राहक प्रतिक्रिया में प्राप्त करना चाहता है। हमारे कनिष्ठ ने एक सर्वर लिखा है जो 200 ठीक देता है, सामग्री-प्रकार: आवेदन / जसन, और एक खाली निकाय पास करता है:

01. DELETE /articles/ 1 /1.1
02. Accept: application/json

01. HTTP/1.1 200 OK
02. Content-Type: application/json
03. null

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

इस स्थिति को कैसे ठीक करें? संभवत: सबसे अच्छा विकल्प जसन पास करना है। यदि हमने कहा: "स्वीकार करें, हमें json दें", तो सर्वर कहता है: "सामग्री-प्रकार, मैं आपको json देता हूं", json दे। एक खाली वस्तु, एक खाली सरणी - वहाँ कुछ रखो - यह समाधान होगा, और यह काम करेगा।

अभी भी एक समाधान है। 200 ओके के अलावा, एक प्रतिक्रिया कोड 204 है - कोई सामग्री नहीं। इसके साथ, आप शरीर को प्रसारित नहीं कर सकते। इस बारे में हर कोई नहीं जानता।

इसलिए मैंने मीडिया प्रकारों का नेतृत्व किया।

माइम के प्रकार

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

• डिफ़ॉल्ट रूप से, यह पाठ / सादा है - केवल पाठ।
• यदि कुछ भी निर्दिष्ट नहीं किया गया है, तो ब्राउज़र सबसे अधिक संभावना है कि आवेदन / ऑक्टेट-स्ट्रीम - बस थोड़ा सा स्ट्रीम हो।

आप केवल एक विशिष्ट प्रकार निर्दिष्ट कर सकते हैं:

• आवेदन / पीडीएफ;
• छवि / पीएनजी;
• आवेदन / जसन;
• आवेदन / xml;
• आवेदन / vnd.ms-excel।

सामग्री-प्रकार और स्वीकार शीर्ष लेख हैं और महत्वपूर्ण हैं।

API और क्लाइंट को सामग्री-प्रकार और हेडर स्वीकार करना होगा।

यदि आपका API JSON पर बनाया गया है, तो हमेशा Accept: application / json और कंटेंट-टाइप एप्लिकेशन / json पास करें।

उदाहरण फ़ाइल प्रकार।


मीडिया प्रकार केवल इंटरनेट पर इन प्रकार की फ़ाइलों के समान हैं।

उत्तर कोड

हमारे जूनियर डेवलपर के कारनामों का अगला उदाहरण प्रतिक्रिया कोड है।



सबसे मजेदार प्रतिक्रिया दर 200 ठीक है। हर कोई उसे प्यार करता है - इसका मतलब है कि सब कुछ सही हो गया। मेरे पास एक मामला भी था - मुझे 200 ओके की त्रुटियां मिलीं। वास्तव में सर्वर पर कुछ गिर गया, प्रतिक्रिया के जवाब में एक HTML पृष्ठ आता है जिस पर एक एचटीएमएल त्रुटि संकलित की गई है। मैंने कोड 200 ओके के साथ एक एप्लीकेशन जसन का अनुरोध किया, और सोचा कि इसके साथ कैसे काम किया जाए? आप प्रतिक्रिया द्वारा जाते हैं, शब्द "त्रुटि" की तलाश करें, आपको लगता है कि यह एक गलती है।

यह काम करता है, हालांकि, HTTP में कई अन्य कोड हैं जिनका आप उपयोग कर सकते हैं, और REST अनुशंसा करता है कि आप उनका उपयोग REST पर करें। उदाहरण के लिए, एक इकाई (लेख) के निर्माण का उत्तर दिया जा सकता है:

• 201 बनाया गया एक सफल कोड है। लेख बनाया गया है, जवाब में आपको बनाए गए लेख को वापस करने की आवश्यकता है।
• 202 स्वीकृत का अर्थ है कि अनुरोध स्वीकार कर लिया गया है, लेकिन इसका परिणाम बाद में होगा। ये लंबे समय तक चलने वाले ऑपरेशन हैं। स्वीकार किए जाने पर, कोई भी शरीर वापस नहीं किया जा सकता है। यही है, यदि आप प्रतिक्रिया में सामग्री-प्रकार नहीं देते हैं, तो शरीर भी नहीं हो सकता है। या सामग्री-प्रकार का पाठ / विमान - यह सब, कोई सवाल नहीं है। एक खाली स्ट्रिंग एक मान्य पाठ / विमान है।
• 204 कोई सामग्री नहीं - शरीर पूरी तरह से अनुपस्थित हो सकता है।
• 403 निषिद्ध - आपको यह लेख बनाने की अनुमति नहीं है।
• 404 नहीं मिला - आप कहीं गलत तरीके से चढ़ गए, उदाहरण के लिए ऐसा कोई रास्ता नहीं है।
• 409 संघर्ष एक चरम मामला है जिसका उपयोग बहुत कम लोग करते हैं। कभी-कभी इसकी आवश्यकता होती है यदि आप क्लाइंट पर आईडी बना रहे हैं, और बैकएंड पर नहीं, और उस समय कोई व्यक्ति पहले से ही इस लेख को बनाने में कामयाब है। इस मामले में संघर्ष सही जवाब है।

इकाई निर्माण

निम्नलिखित उदाहरण: हम एक इकाई बनाते हैं, सामग्री-प्रकार कहते हैं: आवेदन / json, और इस एप्लिकेशन / json को पास करें। यह ग्राहक को हमारा उद्देश्य बनाता है। चलो यह बहुत लेख बनाते हैं:

01. POST /articles /1.1
02. Content-Type: application/json
03. { "id": 1, "title": " JSON API"}

जवाब में कोड आ सकता है:

• 422 असंसाधित इकाई - एक अनुत्पादक इकाई। सब कुछ बहुत अच्छा लगता है - शब्दार्थ, कोड है;
• 403 निषिद्ध
• 500 आंतरिक सर्वर त्रुटि।

लेकिन यह बिल्कुल समझ में नहीं आता कि वास्तव में क्या हुआ: किस प्रकार की इकाई को संसाधित नहीं किया गया है, मुझे वहां क्यों नहीं जाना चाहिए, और आखिरकार सर्वर का क्या हुआ?

वापसी की त्रुटियां

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

बैकएंड प्रतिक्रिया में त्रुटियों के साथ एक सरणी लौटा सकता है, कई हो सकते हैं।

01. HTTP/1.1 422 Unprocessable Entity
02. Content-Type: application/json
03.
04. { "errors": [{
05. "status": "422",
06. "title": "Title already exist",
07. }]}

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

पेजिंग जोड़ें

निम्नलिखित उदाहरण: डिजाइनर हमारी शुरुआत में बैकेंड डेवलपर के पास आते हैं और कहते हैं: "हमारे पास कई लेख हैं, हमें पृष्ठांकन की आवश्यकता है। हमने इसे आकर्षित किया। "


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

हालाँकि, REST API के ऊपर एक कन्वेंशन है जो इस समस्या को हल करता है।

सूची अनुरोध

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

01. GET /articles? page[size]=30&page[number]=2
02. Content-Type: application/json

01. HTTP/1.1 200 OK
02. {
03. "data": [{ "id": 1, "title": "JSONAPI"}, ...],
04. "meta": { "count": 10080 }
05. }

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

पाजिनेशन अलग है। मैं कई जीवन हैक की पेशकश करता हूं जो आप उपयोग कर सकते हैं।

[ऑफसेट] ... [सीमा]

01. GET /articles? page[offset]=30&page[limit]=30
02. Content-Type: application/json

01. HTTP/1.1 200 OK
02. {
03. "data": [{ "id": 1, "title": "JSONAPI"}, ...],
04. "meta": { "count": 10080 }
05. }

डेटाबेस के साथ काम करने वालों के पास पहले से ही एक [ऑफसेट] ... [सीमा] सबकोर्टेक्स हो सकता है। पृष्ठ [आकार] के बजाय इसका उपयोग करना ... पृष्ठ [संख्या] आसान हो जाएगा। यह थोड़ा अलग दृष्टिकोण है।

कर्सर की स्थिति

01. GET /articles? page[published_at]=1538332156
02. Content-Type: application/json

01. HTTP/1.1 200 OK
02. {
03. "data": [{ "id": 1, "title": "JSONAPI"}, ...],
04. "meta": { "count": 10080 }
05. }

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

इस समस्या को कर्सर पेजेशन द्वारा हल किया जाता है। हम कहते हैं: "उस समय प्रकाशित लेख के बाद आने वाले लेखों को लोड करें" - विशुद्ध रूप से तकनीकी रूप से अब कोई बदलाव नहीं हो सकता है, और यह अच्छा है।

समस्या N १

अगली समस्या जो हमारे जूनियर डेवलपर को निश्चित रूप से सामना करेगी, वह एन + 1 समस्या है (बैकेंडर्स समझ जाएगा)। मान लीजिए आप 10 लेखों की सूची बनाना चाहते हैं। हम लेखों की एक सूची अपलोड करते हैं, प्रत्येक लेख में एक लेखक होता है, और प्रत्येक के लिए आपको एक लेखक को डाउनलोड करना होगा। हम जहाज:

• लेखों की सूची के लिए 1 अनुरोध;
• प्रत्येक लेख के लेखकों के लिए 10 अनुरोध।

कुल: एक छोटी सूची प्रदर्शित करने के लिए 11 क्वेरी।

लिंक जोड़ें

बैकएंड पर, यह समस्या सभी ओआरएम में हल हो गई है - आपको बस इस कनेक्शन को जोड़ने के लिए याद रखने की आवश्यकता है। इन कनेक्शनों का उपयोग सामने के छोर पर भी किया जा सकता है। यह निम्नानुसार किया जाता है:

01. GET /articles? include =author
02. Content-Type: application/json

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

01. /1.1 200
02. { "data": [{
03. { attributes: { "id": 1, "title": "JSON API" },
04. { relationships: {
05. "author": { "id": 1, "name": "Avdeev" } }
06. }, ...
07. }]}

स्वयं के लेख विशेषताओं को डेटा में स्थानांतरित कर दिया गया था और प्रमुख रिश्तों को जोड़ा गया था। हमने इस कुंजी में सभी कनेक्शन लगाए। इस प्रकार, एक अनुरोध के साथ, हमें पहले 11 अनुरोध प्राप्त हुए सभी डेटा प्राप्त हुए। यह एक शांत जीवन हैक है जो सामने के छोर पर एन + 1 के साथ समस्या को हल करता है।

डेटा के दोहराव की समस्या

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

चूंकि सभी ऑब्जेक्ट समान हैं, इसलिए समस्या जो एक लेखक को 10 बार (10 एमबी) शामिल है, सामान्यीकरण की मदद से हल की जाती है, जो डेटाबेस में उपयोग की जाती है। सामने के छोर पर, आप एपीआई के साथ काम करने में सामान्यीकरण का उपयोग कर सकते हैं - यह बहुत अच्छा है।

01. /1.1 200
02. { "data": [{
03. "id": "1″, "type": "article",
04. "attributes": { "title": "JSON API" },
05. "relationships": { ... }
06. "author": { "id": 1, "type": "people" } }
07. }, ... ]
08. }

हम सभी संस्थाओं को किसी प्रकार से चिह्नित करते हैं (यह एक प्रतिनिधित्व प्रकार, एक संसाधन प्रकार है)। रॉय फील्डिंग ने एक संसाधन की अवधारणा पेश की, अर्थात्, उन्होंने लेखों का अनुरोध किया - एक "लेख" प्राप्त किया। रिश्तों में, हम टाइप लोगों के लिए एक कड़ी डालते हैं, अर्थात, हमारे पास अभी भी लोगों के संसाधन कहीं और हैं। और संसाधन में हम एक अलग कुंजी शामिल करते हैं, जो डेटा के समान स्तर पर है।

01. /1.1 200
02. {
03. "data": [ ... ],
04. "included": [{
05. "id": 1, "type": "people",
06. "attributes": { "name": "Avdeev" }
07. }]
08. }

इस प्रकार, एक ही उदाहरण में सभी संबंधित निकाय शामिल विशेष कुंजी में आते हैं। हम केवल लिंक को संग्रहीत करते हैं, और निकाय खुद को इसमें शामिल करते हैं।

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

सभी संसाधन क्षेत्रों की आवश्यकता नहीं है

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

GET /articles ?fields[article]=title /1.1

01. /1.1 200 OK
02. { "data": [{
03. "id": "1″, "type": "article",
04. "attributes": { "title": " JSON API" },
05. }, ... ]
06. }

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

लेखों द्वारा खोजें

अक्सर हमें खोज और फ़िल्टर की आवश्यकता होती है। इसके लिए कन्वेंशन हैं - विशेष फिल्टर GET पैरामीटर:

● GET /articles ?filters[search]=api HTTP/1.1 - खोज;
● GET /articles ?fiIters[from_date]=1538332156 HTTP/1.1 - एक विशिष्ट तिथि से लेख डाउनलोड करें;
● GET /articles ?filters[is_published]=true HTTP/1.1 - डाउनलोड लेख जो अभी प्रकाशित हुए हैं;
● GET /articles ?fiIters[author]=1 HTTP/1.1 - पहले लेखक के साथ लेख डाउनलोड करें।

छँटाई लेख

● GET /articles ?sort=title /1.1 - शीर्षक से;
● GET /articles ?sort=published_at HTTP/1.1 - प्रकाशन की तारीख से;
● GET /articles ?sort=-published_at HTTP/1.1 - विपरीत दिशा में प्रकाशन तिथि द्वारा;
● GET /articles ?sort=author,-publisbed_at HTTP/1.1 - पहले लेखक द्वारा, फिर विपरीत दिशा में प्रकाशन तिथि से, यदि लेख एक ही लेखक के हैं।

URL बदलने की आवश्यकता है

समाधान: हाइपरमीडिया, जिसका मैंने पहले ही उल्लेख किया था, निम्नानुसार किया जा सकता है। यदि हम चाहते हैं कि वस्तु (संसाधन) स्व-वर्णन हो, तो क्लाइंट हाइपरमीडिया के माध्यम से समझ सकता है कि इसके साथ क्या किया जा सकता है, और सर्वर ग्राहक के स्वतंत्र रूप से विकसित हो सकता है, तो आप लेखों की सूची में लिंक जोड़ सकते हैं, लेख के लिए स्वयं लिंक लिंक का उपयोग कर। :

01. GET /articles /1.1
02. {
03. "data": [{
04. ...
05. "links": { "self": "http://localhost/articles/1" },
06. "relationships": { ... }
07. }],
08. "links": { "self": " http://localhost/articles " }
09. }

या संबंधित, अगर हम ग्राहक को इस लेख पर टिप्पणी अपलोड करने का तरीका बताना चाहते हैं:

01. ...
02. "relationships": {
03. "comments": {
04. "links": {
05. "self": "http://localhost/articles/l/relationships/comments ",
06. "related": " http://localhost/articles/l/comments "
07. }
08. }
09. }
क्लाइंट देखता है कि एक लिंक है, इसका अनुसरण करता है, एक टिप्पणी लोड करता है। अगर कोई लिंक नहीं है, तो कोई टिप्पणी नहीं है। यह सुविधाजनक है, लेकिन ऐसा बहुत कम लोग करते हैं। रीस्ट के सिद्धांतों के साथ क्षेत्ररक्षण आया, लेकिन उन सभी ने हमारे उद्योग में प्रवेश नहीं किया। हम मुख्य रूप से दो या तीन का उपयोग करते हैं।

2013 में, सभी जीवन हैक जो मैंने आपको बताया, स्टीव क्लेबनिक ने JSON API विनिर्देशन में संयुक्त किया और JSON के शीर्ष पर एक नए मीडिया प्रकार के रूप में पंजीकृत किया। इसलिए हमारे जूनियर बैकएंड डेवलपर, धीरे-धीरे विकसित हो रहे हैं, JSON एपीआई में आए।

JSON एपीआई

सब कुछ http://jsonapi.org/implementations/ पर विस्तार से वर्णित है: 32 प्रोग्रामिंग भाषाओं के लिए 170 विभिन्न विशिष्टताओं के कार्यान्वयन की एक सूची है - और ये केवल कैटलॉग में जोड़े जाते हैं। पुस्तकालयों, पार्सरों, धारावाहिकों आदि को पहले ही लिखा जा चुका है।

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

JSON एपीआई पेशेवरों

JSON एपीआई विनिर्देश कई समस्याओं का हल करता है - सभी के लिए एक सामान्य समझौता । चूंकि एक सामान्य समझौता है, हम टीम के भीतर बहस नहीं करते हैं - साइकिल शेड का दस्तावेजीकरण किया जाता है। साइकिल का शेड बनाने के लिए और इसे कैसे पेंट करना है, इस बारे में हमारा एक समझौता है।

अब, जब डेवलपर कुछ गलत करता है और मैं इसे देखता हूं, तो मैं चर्चा शुरू नहीं करता हूं, लेकिन मैं कहता हूं: "JIV API द्वारा नहीं!" और विनिर्देश में जगह दिखाओ। वे मुझे कंपनी से नफरत करते हैं, लेकिन धीरे-धीरे इसकी आदत हो गई है, और हर कोई JSON एपीआई को पसंद करने लगा है। हम इस विनिर्देशन के अनुसार नई डिफ़ॉल्ट सेवाएं बनाते हैं। हमारे पास तारीख की कुंजी है, हम मेटा जोड़ने के लिए तैयार हैं, चाबियाँ शामिल हैं। फ़िल्टर के लिए एक आरक्षित GET पैरामीटर फ़िल्टर है। हम यह नहीं तर्क देते हैं कि फ़िल्टर को क्या कहा जाए - हम इस विनिर्देश का उपयोग करते हैं। यह बताता है कि URL कैसे बनाया जाता है।

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

लोकप्रिय समस्याओं को पहले से ही हल कर लिया गया है , उदाहरण के लिए, अंकुरण के साथ। कल्पना में बहुत सारे संकेत हैं।

चूंकि यह JSON है (इस प्रारूप के लिए डगलस क्रॉकफोर्ड के लिए धन्यवाद), यह XML की तुलना में अधिक संक्षिप्त है, इसे पढ़ना और समझना काफी आसान है ।

यह तथ्य कि यह ओपन सोर्स है, प्लस और माइनस दोनों हो सकता है, लेकिन मुझे ओपन सोर्स बहुत पसंद है।

विपक्ष JSON एपीआई

ऑब्जेक्ट बड़ा हो गया है (तिथि, गुण, शामिल, आदि) - सामने वाले को जवाबों को पार्स करने की आवश्यकता है: सरणियों पर पुनरावृत्ति करने में सक्षम हो, ऑब्जेक्ट के चारों ओर चलना और पता करें कि काम कैसे कम करें। सभी नौसिखिए डेवलपर्स इन जटिल चीजों को नहीं जानते हैं। धारावाहिकों / deserializers के पुस्तकालय हैं, आप उनका उपयोग कर सकते हैं। सामान्य तौर पर, यह केवल डेटा के साथ काम कर रहा है, लेकिन ऑब्जेक्ट बड़े हैं।

और बैकेंड में दर्द होता है:

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

नुकसान JSON एपीआई

कट्टर सा।

मुद्दे में रिश्तों की संख्या सीमित नहीं है। यदि हम शामिल करते हैं, लेखों का अनुरोध करते हैं, तो उन्हें टिप्पणी जोड़ते हैं, तो जवाब में हम इस लेख के सभी टिप्पणियों को प्राप्त करेंगे। 10,000 टिप्पणियां हैं - सभी 10,000 टिप्पणियां प्राप्त करें:

GET /articles/1?include=comments /1.1

01. ...
02. "relationships": {
03. "comments": {
04. "data": [0 ... ∞]
05. }
06. }

इस प्रकार, वास्तव में 5 एमबी हमारे जवाब में आया: "यह विनिर्देश में लिखा गया है - अनुरोध को सही ढंग से सुधारना आवश्यक है:

GET /comments? filters[article]=1& page[size]=30 HTTP/1.1

01. {
02. "data": [0 ... 29]
03. }

हम लेख द्वारा फ़िल्टर के साथ टिप्पणियों का अनुरोध करते हैं, कहते हैं: "30 टुकड़े, कृपया" और 30 टिप्पणियाँ प्राप्त करें। यह अस्पष्टता है।

वही चीजें अस्पष्ट रूप से तैयार की जा सकती हैं :

● GET /articles/1 ?include=comments HTTP/1.1 - टिप्पणियों के साथ एक लेख का अनुरोध करें;
● GET /articles/1/comments HTTP/1.1 - लेख पर टिप्पणी का अनुरोध करें;
● GET /comments ?filters[article]=1 HTTP/1.1 - लेख द्वारा एक फिल्टर के साथ टिप्पणियों का अनुरोध करें।

यह एक और एक ही है - एक ही डेटा, जो अलग-अलग तरीकों से प्राप्त होता है, कुछ अस्पष्टता है। यह नुकसान तुरंत नहीं दिख रहा है।

एक से कई बहुपत्नी संबंध REST में बहुत जल्दी रेंगते हैं।

01. GET /comments?include=commentable /1.1
02.
03. ...
04. "relationships": {
05. "commentable" : {
06. "data": { "type": "article", "id": "1″ }
07. }
08. }

बैकएंड पर एक उल्लेखनीय पॉलीमॉर्फिक कनेक्शन है - यह आरईएसटीटी में क्रॉल करता है। तो यह होना चाहिए, लेकिन यह प्रच्छन्न हो सकता है। आप इसे JSON API में नहीं बदल सकते - यह सामने आ जाएगा।

उन्नत विकल्पों के साथ कई-से-कई संबंध जटिल । इसके अलावा, सभी कनेक्टिंग टेबल बाहर आते हैं:

01. GET /users?include =users_comments /1.1
02.
03. ...
04. "relationships": {
05. "users_comments": {
06. "data": [{ "type": "users_comments", "id": "1″ }, ...]
07. },
08. }

अकड़

स्वैगर एक ऑनलाइन प्रलेखन लेखन उपकरण है।

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

उदाहरण: स्वैगर पालतू जानवर की दुकान। प्रत्येक विधि को खोला जा सकता है, प्रतिक्रिया और उदाहरण देख सकते हैं।



यह एक पालतू मॉडल का एक उदाहरण है। यहां एक शांत इंटरफ़ेस है, सब कुछ पढ़ना आसान है।



और इस तरह JSON API मॉडल का निर्माण कैसा दिखता है:



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

विकल्प

एक ओडेटा विनिर्देश है, जो थोड़ी देर बाद दिखाई दिया - 2015 में। यह "REST का सबसे अच्छा तरीका है", जैसा कि आधिकारिक वेबसाइट ने आश्वासन दिया है। यह इस तरह दिखता है:

01. GET http://services.odata.org/v4/TripRW/People HTTP/1.1 - GET अनुरोध;
02. OData-Version: 4.0 - संस्करण के साथ विशेष हेडर;
03. OData-MaxVersion: 4.0 - दूसरा विशेष संस्करण हैडर

जवाब इस तरह दिखता है:

01. HTTP/1.1 200 OK
02. Content-Type: application/json; odata.metadata=minimal
03. OData-Version: 4.0
04. {
05. '@odata.context': 'http://services.odata.org/V4/
06. '@odata.nextLink' : 'http://services.odata.org/V4/
07. 'value': [{
08. '@odata.etag': 1W/108D1D5BD423E51581′,
09. 'UserName': 'russellwhyte',
10. ...

यहाँ विस्तारित अनुप्रयोग / json और ऑब्जेक्ट है।

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

GraphQL के बारे में क्या?

स्वाभाविक रूप से, जब हम एक नए एपीआई प्रारूप की तलाश कर रहे थे, हम इस प्रचार में भाग गए।

● उच्च प्रवेश सीमा।

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

● बड़े धमाके का असर।

यदि परियोजना में कोई एपीआई नहीं था, और हमने ग्राफ़कलाइन का उपयोग करना शुरू कर दिया, तो एक महीने के बाद हमने महसूस किया कि यह हमें सूट नहीं करता है, बहुत देर हो जाएगी। बैसाखी लिखनी है। आप JSON API या OData के साथ विकसित हो सकते हैं - सबसे सरल Restful, उत्तरोत्तर सुधार, JSON API में बदल जाता है।

● बैकएंड पर नरक।

ग्राफकॉक बैकएंड पर नरक को बुलाता है - एक पर एक, पूरी तरह से लागू JSON API की तरह, क्योंकि ग्राफ़कॉल को प्रश्नों पर पूर्ण नियंत्रण प्राप्त है, और यह एक पुस्तकालय है, और आपको बहुत सारे मुद्दों को हल करने की आवश्यकता होगी:

• घोंसला नियंत्रण;
• प्रत्यावर्तन;
• आवृत्ति सीमा;
• अभिगम नियंत्रण।

निष्कर्ष के बजाय

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

साइकिल शेड की समस्या को हल करने के लिए अपना मानक खोजने के लिए, आप इन लिंक को देख सकते हैं:

● http://jsonapi.org
● http://www.odata.org
● https://graphgl.org
● http://xmlrpc.scripting.com
● https://www.jsonrpc.org

: alexey-avdeev.com github .

, Frontend Conf , 27 28 ++ . , .

? ? ? , ? !

, , , , .