हमने सामाजिक नेटवर्क के लिए एपीआई कैसे किया (REST API for WEB)

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

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

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

मुझे तुरंत यह बताना होगा कि मैं एक प्रोग्रामर हूं, लेखक नहीं, और यह मेरा पहला लेख है। शायद यह सूखा निकला, लेकिन हम सभी तकनीकी विशेषज्ञ हैं, मुझे उम्मीद है कि यह दिलचस्प होगा। इस लेख में मैं REST API के साथ अपने अनुभव का वर्णन करूंगा। मैं लेख को सार्वभौमिक बनाने का प्रयास करूंगा ताकि मेरे लेख में इस विचारधारा को किसी भी इंटरनेट परियोजना पर लागू किया जा सके।

अब क्रम से चलते हैं।

बाकी (प्रतिनिधि राज्य स्थानांतरण)।

रॉय फील्डिंग - 2000 में REST वापस नामक एक दृष्टिकोण का वर्णन किया, इस दृष्टिकोण ने प्रसिद्ध HTTP प्रोटोकॉल का आधार बनाया। इस वास्तुकला प्रोग्रामिंग शैली के लिए दो प्रकार के लेखन हैं: REST और RESTful, इन शब्दों के अर्थ में कोई अंतर नहीं है, बस RESTful REST का विशेषण है, अर्थात, RESTful API एक API है जो REST के सिद्धांतों से मिलता है (मैं उन लोगों से माफी मांगता हूं जो जानते थे लेकिन इस तरह के सवाल अक्सर पूछे जाते हैं)।

बाकी (प्रतिनिधि राज्य स्थानांतरण)।

अन्य एपीआई संरचना

1. क्लाइंट-सर्वर आर्किटेक्चर

2. स्टेटलेस सर्वर

3. कैचपबिलिटी

4. बहुपरत संरचना

5. एकीकृत इंटरफ़ेस

• संसाधन की पहचान
• अभ्यावेदन के माध्यम से संसाधनों के साथ सहभागिता
• स्व-निहित संदेश
• हाइपरमीडिया एक एप्लीकेशन स्टेट मैनेजमेंट मैकेनिज्म (HATEOAS) के रूप में

6. मांग पर कोड (वैकल्पिक)

अब प्रत्येक तत्व के बारे में अधिक विस्तार से।

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

स्टेटलेस - सर्वर। क्लाइंट की स्थिति सर्वर पर संग्रहीत नहीं है, किसी भी रूप में, यह विशेष रूप से क्लाइंट द्वारा किया जाता है। यह सर्वर के पूरा होने और रखरखाव को सरल करता है, इसे और अधिक स्थिर बनाता है।

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

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

एकीकृत इंटरफ़ेस।

संसाधन की पहचान। प्रत्येक संसाधन में एक अद्वितीय URI (यूनिफ़ॉर्म रिसोर्स आइडेंटिफ़ायर) होता है। उदाहरण के लिए:

/ उपयोगकर्ता / ae25b8

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

/ उपयोगकर्ता / 550e8400-e29b-41d4-a716-446655440000

अभ्यावेदन के माध्यम से संसाधनों के साथ सहभागिता। प्रत्येक संसाधन का अपना विशिष्ट यूआरआई (प्रतिनिधित्व) है, और इस प्रतिनिधित्व को नियंत्रित करने के लिए कई क्रियाएं हैं।

स्व-निहित संदेश। प्रत्येक उत्तर में सभी आवश्यक जानकारी होनी चाहिए ताकि इसे अन्य संसाधनों की सहायता के बिना सही ढंग से संसाधित किया जा सके।

HATEOAS। हाइपरमीडिया अनुप्रयोग राज्य के इंजन के रूप में।

आवेदन राज्यों के प्रबंधन के लिए एक तंत्र के रूप में हाइपरमीडिया।

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

HATEOAS को समझने की कुंजी आश्चर्यजनक रूप से सरल है - प्राप्त प्रत्येक प्रतिक्रिया में अगले अनुरोध का लिंक शामिल है।

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

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

मांग पर कोड। संरचना का वैकल्पिक तत्व। आपको क्लाइंट पर इसके बाद के निष्पादन के लिए प्रोग्राम कोड प्राप्त करने की अनुमति देता है।

इस प्रकार, यदि आपका आवेदन ऊपर वर्णित सभी आवश्यकताओं (प्रतिबंधों) को पूरा करता है, तो इसे सुरक्षित रूप से RESTful कहा जा सकता है। एक अपवाद केवल मांग पर एक कोड है - यह पैरामीटर वैकल्पिक है।

एक अच्छा एपीआई समझने में आसान और उपयोग में आसान है।

HTTP पर REST की मूल बातें।

एक संसाधन एक अद्वितीय URL द्वारा सुलभ एक अद्वितीय वस्तु है।

मूल URL बिना दस्तावेज के स्पष्ट होना चाहिए।

शुरू करने के लिए, उदाहरण के लिए, उपसर्ग के साथ अपने एपीआई के सभी URL को शुरू करना उचित है:

/ एपी /

यह भविष्य में एपीआई रखरखाव को सरल बनाने में मदद करेगा। एक अच्छा विकल्प डोमेन नाम को उपसर्ग करना हो सकता है:

api.example.com/users/ae25b8

REST वास्तुकला में 2 मुख्य प्रकार के संसाधन हैं : संग्रह और संग्रह तत्व ।

संग्रह स्वतंत्र और आत्मनिर्भर तत्वों का एक समूह है।

उदाहरण उपयोगकर्ता संग्रह लिंक:

/ एपीआई / उपयोगकर्ताओं

उपयोगकर्ता संग्रह का एक तत्व, या एक विशिष्ट उपयोगकर्ता, इस मामले में, के रूप में प्रतिनिधित्व किया जा सकता है:

/ एपीआई / उपयोगकर्ता / ae25b8

संज्ञाएँ अच्छी हैं, क्रियाएँ बुरी हैं।

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

RESTful API में प्रत्येक संसाधन को कई परिभाषित न्यूनतम आवश्यक क्रियाओं द्वारा प्रबंधित किया जाता है। अधिकांश मामलों के लिए, 4 मूल क्रियाएं (HTTP विधि) पर्याप्त हैं:

मिलता है - मिलता है

पोस्ट - बनाएँ

PUT - परिवर्तन

DELETE - हटाएं

GET, PUT, DELETE - बेकार।

Idempotency का अर्थ है कि हम चाहे कितनी भी बार इस विधि को क्यों न कहें, परिणाम समान होगा।

संसाधन	पोस्ट	प्राप्त	PUT	हटाएँ
/ उपयोगकर्ता	उपयोगकर्ता बनाएँ	सभी उपयोगकर्ताओं की सूची दिखाएं	सभी उपयोगकर्ताओं की सूची को ताज़ा करें	सभी उपयोगकर्ताओं को हटा दें
/ उपयोगकर्ता / ae25b8	त्रुटि	वैसिली पुपकिन दिखाएं	अगर वहाँ है, तो पुपकिन को अपडेट करें, यदि नहीं	वसीली प्यूपकिन निकालें

संचार।

यदि वस्तुओं के बीच एक पदानुक्रमित संबंध दिखाना आवश्यक है, तो हम ऐसा करते हैं।

उपयोगकर्ता मशीन संग्रह:

/ एपीआई / उपयोगकर्ताओं / ae43bc / कारों

विशिष्ट मशीन:

/ एपीआई / उपयोगकर्ताओं / ae43bc / कारों / c7b45e

लंबे पते न लिखें - यह बुरा है:

/ एपीआई / उपयोगकर्ता / ae43bc / कारें / c7b45e / दरवाजा / 346ec3b

इस तरह के पते प्रलेखन में पढ़ने और देखने के लिए आसान नहीं हैं, अक्सर इसका कोई मतलब नहीं है - पहचानकर्ता अद्वितीय हैं और "/ कारें / c7b45e" बिल्कुल असमान रूप से "/ उपयोगकर्ताओं / ae43bc" को संदर्भित करता है। इस विकल्प को कम किया जाना चाहिए:

/ एपीआई / कार / c7b45e / दरवाजा / 346ec3b

त्रुटि।

स्टेटस कोड्स (HTTP स्टेटस कोड) के 2 मुख्य परिवार हैं:

4xx - समस्या उपयोगकर्ता की तरफ से उत्पन्न हुई और वह स्वयं अनुरोध के लिए आवश्यक जानकारी दर्ज करके इसे ठीक कर सकता है।

5xx - सर्वर पर समस्या उत्पन्न हुई और इसे हल करने के लिए, उपयोगकर्ता समर्थन सेवा के लिए अनुरोध भेज सकता है।

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

एक लिखित त्रुटि प्रतिक्रिया का एक उदाहरण:

HTTP स्थिति कोड: 401

{"स्थिति": 401, "संदेश": "प्रमाणीकरण आवश्यक", "कोड": 20003, "more_info": "http://www.example.com/docs/errors/20003"}

याद रखें! आप के रूप में एक ही डेवलपर्स के लिए एक एपीआई लिख रहे हैं।

एप्लिकेशन में आवश्यक न्यूनतम स्थिति कोड का उपयोग करें।

कभी-कभी 3 पर्याप्त हो सकते हैं:

1. 200 ठीक है
2. 400 बुरा अनुरोध
3. 500 आंतरिक सर्वर त्रुटि

यदि छोटा हो, तो आवश्यकतानुसार पूरक:

1. 201 बनाया गया (सफलतापूर्वक बनाया गया)
2. 304 संशोधित नहीं (डेटा नहीं बदला गया है)
3. 404 नहीं मिला
4. 401 अनधिकृत (अधिकृत नहीं)
5. 403 निषिद्ध (पहुंच अस्वीकृत)

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

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

PUT / api / users / de840a? Supress_status_code = 200

यह आपके एपीआई में अतिरिक्त लचीलापन जोड़ देगा।

संस्करण।

संस्करण संख्या निर्दिष्ट करना सुनिश्चित करें, भले ही आप इंटरफ़ेस को बदलने की योजना न करें - सब कुछ जल्दी से बदल सकता है।

संस्करण को पता बार में निर्दिष्ट किया जा सकता है:

/ एपीआई / वी 2 / उपयोगकर्ता / ae43bc

या क्वेरी मापदंडों में:

/ एपीआई / उपयोगकर्ता / ae43bc? v = 2

यह संस्करण नाम बनाने के लिए कोई मतलब नहीं है, उन में डॉट्स डालें: v1.03

इंटरफ़ेस संस्करणों को यथासंभव कम से कम बदलना चाहिए, जबकि आवश्यकता पड़ने पर एपीआई के आंतरिक तर्क को बदला जा सकता है। वास्तव में, एपीआई का वास्तविक संस्करण हो सकता है, उदाहरण के लिए, v2.034-beta2, लेकिन इंटरफ़ेस का संस्करण और, तदनुसार, पते में प्रस्तुत संस्करण सिर्फ 2 होगा।

पृष्ठ-मुद्दा।

कोई भी संग्रह, चाहे वह कितना भी छोटा हो, आपकी राय में, पृष्ठ द्वारा पृष्ठ नहीं दिया जाना चाहिए। संग्रह प्रारूप पर निर्णय लें, उदाहरण के लिए, सामग्री-प्रकार: अनुप्रयोग / json {"डेटा": {}, "पेजिंग": {"सीमा": 50, "ऑफसेट": 0, "कुल": 150}} हमेशा उपयोग करने का प्रयास करें आवेदन के सभी उत्तरों में एक ही प्रारूप - अपने और क्लाइंट सॉफ्टवेयर डेवलपर्स दोनों के लिए जीवन को आसान बनाते हैं।

यह "सीमा", "ऑफसेट", और सबसे अधिक संभावना है कि "सीमा" के लिए अधिकतम मूल्य को सीमित करने के लिए कुछ प्रकार के डिफ़ॉल्ट मान चुनने के लायक है।

"?" के पीछे सभी जटिल क्वेरी घटकों को छिपाएं।

यदि आपको अपने GET अनुरोध में विभिन्न फ़िल्टर का उपयोग करने की आवश्यकता है, तो उन्हें प्रश्न चिह्न (URL पैरामीटर में) के पीछे रखें।

GET / एपीआई / उपयोगकर्ता? सीमा = 10 और ऑफसेट = 4 और आयु = 30 और ऊंचाई = 160 और वजन = 120

उपयोगकर्ता को केवल वही दें जो वह चाहता है।

क्लाइंट को केवल उन्हीं फ़ील्डों को प्राप्त करने की अनुमति दें, जिनमें उनकी आवश्यकता हो:

GET / api / users / ae43bc? फील्ड्स = fitst_name, last_name, उम्र, लिंग, उंगली

दिए गए डेटा का प्रारूप।

अपने आप को सिर्फ एक प्रारूप तक सीमित न रखें। कुछ वैकल्पिक बनाएं, उदाहरण के लिए, json और xml। ऐसे आसान तरीके से, ग्राहकों के लिए विकास को बहुत सरल बनाया जा सकता है, और किसी एक को चुनने की आवश्यकता नहीं है। रिटर्न किए गए डेटा का प्रारूप HTTP हेडर और क्वेरी स्ट्रिंग दोनों में वर्णित किया जा सकता है:

ACCEPT: आवेदन / जसन

GET /api/users/ae43bc.json

और आपको निश्चित रूप से कुछ डिफ़ॉल्ट प्रारूप चुनना चाहिए।

खोजें।

यह कुछ प्रकार के संसाधनों में से एक है जो एक क्रिया के रूप में रहने के लिए नियत है। मेरा मतलब है वैश्विक खोज।

GET / api / search? Q = some + text + to + find

फिर से, प्रयुक्त खोज इंजन की प्रणाली के आधार पर, विभिन्न फ़िल्टर लागू किए जा सकते हैं।

संग्रह के भीतर कुछ स्थानीय खोज, साधारण फिल्टर के साथ की जा सकती है:

GET / api / users? Q = some + users + to + find

प्राधिकरण।

उपयोग करें, यदि संभव हो तो, OAuth - OAuth 2.0 का नवीनतम संस्करण - यह प्रणाली डेवलपर्स के लिए अच्छी तरह से जानी जाती है, और इसके लायक साबित हुई है। बाइक का आविष्कार क्यों?

प्रलेखन।

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

संदर्भ।

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

अब सबसे महत्वपूर्ण बात!

एपीआई के लिए मुखौटा पैटर्न।

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

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

निष्कर्ष में कुछ शब्द

परिणामस्वरूप, टीम और मैंने सफलतापूर्वक एक सामाजिक नेटवर्क बनाया, जिसमें हमने REST API का उपयोग किया। नेटवर्क, वैसे, PHP में था, विशेष रूप से Symfony2 में, हालांकि यह दृष्टिकोण अन्य प्रौद्योगिकियों पर भी लागू होता है। मुझे उम्मीद है कि मेरा पहला लेख आपके लिए दिलचस्प था। मुझे टिप्पणियों और प्रश्नों को सुनने में खुशी होगी।

मैं आपको डिजिटोव बिजनेस स्कूल से वेब विकास के पाठ्यक्रमों के लिए आमंत्रित करता हूं, जो मैं सिखाता हूं : मैं एक जूनियर PHP डेवलपर बनना चाहता हूं! (शुरुआती के लिए), सिम्फनी 2. लचीले विकास (विशेषज्ञों के लिए), साथ ही साथ मेरे सहयोगियों द्वारा किए गए: पायथन / Django (शुरुआती के लिए) और रूबी पर पटरियों में वेब अनुप्रयोग विकास । पेशेवर विकास के लिए रेल पर (शुरुआती के लिए)। अभी पाठ्यक्रमों की सदस्यता लें और आप उन्हें छूट पर खरीद सकते हैं

PS दूसरों से पहले हमारे नए लेख प्राप्त करने के लिए या नए प्रकाशनों को याद नहीं करने के लिए - SECL समूह के प्रशंसक पृष्ठों की सदस्यता लें: फेसबुक , वीके और ट्विटर

मूल लेख: http://secl.com.ua/article_rest_api_web.html

सर्गेई हार्लानचुक, वरिष्ठ PHP डेवलपर / टीम लीड, एसईसीएल ग्रुप / इंटरनेट सेल्स टेक्नोलॉजीज द्वारा पोस्ट किया गया