rest ट्यूटोरियल
आराम के साथ शुरुआत करना

Android AngularJS C# Language Django Java Language JavaScript Node.js PHP Python Language spring

टिप्पणियों

यह खंड बाकी क्या है का अवलोकन प्रदान करता है, और क्यों एक डेवलपर इसका उपयोग करना चाहता है।

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

बाकी अवलोकन

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

पता योग्य संसाधन: REST में सूचना और डेटा का मुख्य अमूर्त एक संसाधन है और प्रत्येक संसाधन को एक URI के माध्यम से पता होना चाहिए।
एक समान, संकुचित इंटरफ़ेस: हमारे संसाधनों में हेरफेर करने के लिए अच्छी तरह से परिभाषित तरीकों के छोटे सेट का उपयोग।
प्रतिनिधित्व-उन्मुख: एक यूआरआई द्वारा संदर्भित संसाधन में अलग-अलग प्रारूप हो सकते हैं और विभिन्न प्लेटफार्मों को विभिन्न स्वरूपों की आवश्यकता होती है, उदाहरण के लिए ब्राउज़रों को HTML, जावास्क्रिप्ट की आवश्यकता होती है JSON और Java अनुप्रयोगों को XML, JSON, CSV, पाठ, आदि की आवश्यकता हो सकती है, इसलिए हम सेवाओं के साथ सहभागिता करते हैं उस सेवा के प्रतिनिधित्व का उपयोग करना।
स्टेटिकली स्टेटिकली करें: स्टेटलेस एप्लिकेशनों को स्केल करना आसान है।
हाइपरमीडिया एप्लिकेशन के इंजन के रूप में: हमारे डेटा फॉर्मेट को हमारे एप्लिकेशन में स्टेट ट्रांज़िशन चलाते हैं।

इन वास्तु सिद्धांतों के सेट को REST कहा जाता है। REST की अवधारणाएं HTTP से प्रेरित हैं। रॉय फील्डिंग जिसने हमें REST दिया, वह भी HTTP विशिष्टताओं के लेखकों में से एक है।

वेब सेवाएँ और रैस्टफुल वेब सेवाएँ ऐसी सेवाएँ हैं जो प्रोग्रामेटिक एक्सेस के लिए इंटरनेट के संपर्क में हैं। वे ऑनलाइन एपीआई हैं जिन्हें हम अपने कोड से कॉल कर सकते हैं। "बिग" वेब सेवाओं SOAP और REST वेब सेवाओं के दो प्रकार हैं।

रेस्टफुल वेब सर्विसेज : REST आर्किटेक्चरल कॉन्सेप्ट्स को लागू करके लिखी जाने वाली वेब सर्विसेज को Restful Web Services कहा जाता है, जो सिस्टम रिसोर्स पर फोकस करते हैं और कैसे रिसोर्स की स्थिति को HTTP प्रोटोकॉल से अलग क्लाइंट्स में ट्रांसफर किया जा सकता है।

यह दस्तावेज़ पूरी तरह से Restful वेब सेवाओं पर केंद्रित है इसलिए हम SOAP WS के विवरण में नहीं आएंगे।

Restful वेब सेवाओं की तरह डिजाइन करते समय कोई सख्त नियम नहीं हैं

कोई प्रोटोकॉल मानक नहीं
कोई संचार चैनल मानक नहीं
कोई सेवा परिभाषा मानक नहीं

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

रेस्टफुल वेब सर्विसेज की अवधारणा

Restful api को डिजाइन / विकसित करते समय कुछ दिशानिर्देशों पर विचार किया जाना चाहिए:

संसाधन आधारित स्थान / URI
HTTP विधियों का उचित उपयोग
HATEOAS (अनुप्रयोग राज्य के इंजन के रूप में हाइपरमीडिया)

RESTful API को विकसित करते समय मुख्य दृष्टिकोण API को "जितना संभव हो उतना Restful" बनाना चाहिए।

HTTP पर REST

REST एक प्रोटोकॉल-अज्ञेय वास्तुकला है जिसे रॉय फील्डिंग ने अपने शोध प्रबंध में प्रस्तावित किया है (अध्याय 5 REST की प्रस्तुति), जो कि सर्वरों से वितरित सिस्टम में क्लाइंट्स को डिकूप करने के लिए क्लाइंट के रूप में वेब ब्राउज़र की सिद्ध अवधारणा को सामान्य करता है।

किसी सेवा या API को RESTful होने के लिए, उसे दी गई बाधाओं का पालन करना होगा:

क्लाइंट सर्वर
राज्यविहीन
संचित करने योग्य
स्तरित प्रणाली
यूनिफ़ॉर्म इंटरफ़ेस
- संसाधनों की पहचान
- संसाधन प्रतिनिधित्व
- स्व-वर्णनात्मक संदेश
- हाइपरमीडिया

फील्डिंग के शोध प्रबंध में उल्लिखित बाधाओं के अलावा, अपने ब्लॉग पोस्ट में REST API को हाइपरटेक्स्ट-चालित होना चाहिए , फील्डिंग ने स्पष्ट किया कि बस HTTP के माध्यम से किसी सेवा को लागू करना इसे RESTful नहीं बनाता है । इसलिए एक सेवा को आगे के नियमों का भी सम्मान करना चाहिए जिन्हें संक्षेप में निम्नानुसार किया गया है:

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

रिचर्डसन परिपक्वता मॉडल

रिचर्डसन मैच्योरिटी मॉडल Restful वेब सेवाओं को प्राप्त करने के लिए HTTP पर REST बाधाओं को लागू करने का एक तरीका है।

लियोनार्ड रिचर्डसन ने इन 4 परतों में अनुप्रयोगों को विभाजित किया:

स्तर 0: परिवहन के लिए HTTP का उपयोग
स्तर 1: संसाधनों की पहचान करने के लिए URL का उपयोग
स्तर 2: इंटरैक्शन के लिए HTTP क्रियाओं और स्थितियों का उपयोग
स्तर 3: HATEOAS का उपयोग

जैसा कि एक संसाधन की स्थिति पर ध्यान केंद्रित किया जाता है, एक ही संसाधन के लिए कई अभ्यावेदन को प्रोत्साहित किया जाता है। एक प्रतिनिधित्व इसलिए संसाधन राज्य का अवलोकन प्रस्तुत कर सकता है जबकि दूसरा उसी संसाधन का पूरा विवरण देता है।

यह भी ध्यान दें कि फील्डिंग की दिक्कतों को देखते हुए, आरएमएम के तीसरे स्तर के लागू होने के बाद ही एपीआई प्रभावी रूप से RESTful है ।

HTTP अनुरोध और प्रतिक्रियाएँ

एक HTTP अनुरोध है:

एक क्रिया (उर्फ विधि), अधिकांश समय GET , POST , PUT , DELETE या PATCH में से एक
एक URL
हेडर (मुख्य-मूल्य जोड़े)
वैकल्पिक रूप से एक शरीर (उर्फ पेलोड, डेटा)

एक HTTP प्रतिक्रिया है:

एक स्थिति, अधिकांश समय 2xx (सफल) , 4xx (क्लाइंट त्रुटि) या 5xx (सर्वर त्रुटि) में से एक
हेडर (मुख्य-मूल्य जोड़े)
एक शरीर (उर्फ पेलोड, डेटा)

HTTP क्रिया विशेषताएं:

वे क्रियाएं जिनमें एक शरीर होता है: POST , PUT , PATCH
वे क्रियाएं जो सुरक्षित होनी चाहिए (यानी कि संसाधनों को संशोधित नहीं करना चाहिए): GET
वे शब्द जो अनिवार्य होने चाहिए (अर्थात जो कई बार चलने पर संसाधनों को फिर से प्रभावित न GET ): GET (अशक्त), PUT , DELETE

        body  safe  idempotent
GET      ✗     ✔     ✔
POST     ✔     ✗     ✗
PUT      ✔     ✗     ✔
DELETE   ✗     ✗     ✔
PATCH    ✔     ✗     ✗

नतीजतन , HTTP क्रियाओं की तुलना CRUD कार्यों से की जा सकती है :

सी रीट : POST
आर ईएडी: GET
U PDATE : PUT , PATCH
D ELETE : DELETE

ध्यान दें कि एक PUT अनुरोध ग्राहकों को अद्यतन मूल्यों के साथ संपूर्ण संसाधन भेजने के लिए कहता है । किसी संसाधन को आंशिक रूप से अपडेट करने के लिए, एक PATCH क्रिया का उपयोग किया जा सकता है (देखें कि संसाधन को आंशिक रूप से कैसे अपडेट किया जाए? )।

सामान्य HTTP प्रतिक्रिया स्थिति

सफलता

201 ( सृजित ) : संसाधन बनाया गया है
202 ( स्वीकृत ) : अनुरोध स्वीकार किया गया, लेकिन प्रक्रिया अभी भी जारी है
204 (कोई सामग्री) : अनुरोध पूरा हुआ, और कोई अतिरिक्त सामग्री नहीं
अन्यथा: 200 (ठीक है)

पुनर्निर्देशन

304 (संशोधित नहीं) : ग्राहक उस कैश्ड संस्करण का उपयोग कर सकता है जिसका अनुरोध संसाधन के पास है

ग्राहक त्रुटियों

401 (UNAUTHORIZED) : एक अनाम अनुरोध एक संरक्षित एपीआई का उपयोग करता है
403 (FORBIDDEN) : एक प्रमाणित अनुरोध एक संरक्षित एपीआई तक पहुंचने के लिए पर्याप्त अधिकार नहीं है
404 (फ़ाउंड नहीं) : संसाधन नहीं मिला
409 (CONFLICT) : संघर्ष में संसाधन की स्थिति (उदाहरण के लिए पहले से पंजीकृत ईमेल के साथ एक खाता बनाने की कोशिश करने वाला उपयोगकर्ता)
410 (गया) : 404 के समान, लेकिन संसाधन मौजूद था
412 (सटीक विफल) : अनुरोध एक अप्रत्याशित अवस्था में मौजूद संसाधन को संशोधित करने का प्रयास करता है
422 (अपरिहार्य सुरक्षा) : अनुरोध पेलोड वाक्यविन्यास रूप से मान्य है, लेकिन शब्दार्थ त्रुटिपूर्ण है (उदाहरण के लिए आवश्यक फ़ील्ड जिसे मूल्यवान नहीं किया गया है)
423 ( लॉक ) : संसाधन बंद है
424 (विफल हुआ) : किसी अन्य कार्रवाई पर निर्भर कार्रवाई का अनुरोध किया जो विफल रही
429 (TOO MANY REQUESTS) : एक निश्चित समय में उपयोगकर्ता ने कई अनुरोध भेजे
अन्यथा: 400 (BAD REQUEST)

सर्वर त्रुटियों

501 (आवश्यक नहीं) : सर्वर अनुरोध को पूरा करने के लिए आवश्यक कार्यक्षमता का समर्थन नहीं करता है
503 (सेवा उपलब्ध) : सर्वर वर्तमान में अस्थायी अधिभार या अनुसूचित रखरखाव के कारण अनुरोध को संभालने में असमर्थ है
507 (INSUFFICIENT STORAGE) : सर्वर अनुरोध को सफलतापूर्वक पूरा करने के लिए आवश्यक प्रतिनिधित्व को संग्रहीत करने में असमर्थ है
अन्यथा: 500 (आंतरिक सर्वर त्रुटि)

ग्राहकों के लिए अस्वीकृति को स्पष्ट करने के लिए, गलत प्रतिक्रियाओं के लिए शरीर को जोड़ने से कुछ भी नहीं रोकता है। उदाहरण के लिए, 422 (UNPROCESSABLE ENTITY) थोड़ा अस्पष्ट है: प्रतिक्रिया शरीर को वह कारण प्रदान करना चाहिए जिससे इकाई को संसाधित नहीं किया जा सकता है।

HATEOAS

प्रत्येक संसाधन को उन संसाधनों से हाइपरमीडिया प्रदान करना होगा जो इससे जुड़ा हुआ है। एक लिंक कम से कम द्वारा रचित है:

एक rel ( rel ation, aka नाम के लिए): मुख्य संसाधन और लिंक किए गए (s) के बीच के संबंध का वर्णन करता है
एक href : लिंक किए गए संसाधन को लक्षित करने वाला URL

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

Cormac Mulhall बताती है कि क्लाइंट को यह तय करना चाहिए कि HTTP वर्ब के उपयोग के आधार पर यह क्या करने की कोशिश कर रहा है । जब संदेह होता है, तो एपीआई प्रलेखन को आपको सभी हाइपरमीडिया के साथ उपलब्ध इंटरैक्शन को समझने में मदद करनी चाहिए।

मीडिया प्रकार

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

यद्यपि application/json और application/xml काफी लोकप्रिय मीडिया-प्रकार हैं, लेकिन उनमें बहुत शब्दार्थ नहीं हैं। वे सिर्फ दस्तावेज़ में उपयोग किए गए समग्र वाक्यविन्यास का वर्णन करते हैं। HATEOAS आवश्यकताओं का समर्थन करने वाले अधिक विशिष्ट मीडिया-प्रकारों का उपयोग किया जाना चाहिए (या विक्रेता मीडिया प्रकारों के माध्यम से विस्तारित), जैसे:

एक क्लाइंट एक सर्वर को बताता है कि वह किस प्रकार के मीडिया को Accept , उदाहरण के लिए उसके हेडर को Accept :

Accept: application/hal+json

यदि सर्वर ऐसे प्रतिनिधित्व में अनुरोधित संसाधन का उत्पादन करने में सक्षम नहीं है, तो यह 406 (स्वीकार्य नहीं) है । अन्यथा, यह उदाहरण के लिए, प्रतिनिधित्व संसाधन पकड़े हुए Content-Type हेडर में मीडिया प्रकार जोड़ता है:

Content-Type: application/hal+json

स्टेटलेस> स्टेटफुल

क्यों?

एक स्टेटफुल सर्वर का अर्थ है कि क्लाइंट सेशन सर्वर-इंस्टेंस-लोकल स्टोरेज (लगभग हमेशा वेब सर्वर सेशन में) में स्टोर किए जाते हैं। क्षैतिज रूप से स्केल करने का प्रयास करते समय यह एक समस्या होने लगती है: यदि आप लोड बैलेंसर के पीछे कई सर्वर इंस्टेंस छिपाते हैं, यदि किसी क्लाइंट को साइन इन करते समय # 1 को उदाहरण के लिए भेजा जाता है, लेकिन उदाहरण के लिए संरक्षित संसाधन प्राप्त करते समय उदाहरण # 2 के बाद। , तो दूसरा उदाहरण अनुरोध को एक अनाम के रूप में संभाल लेगा, क्योंकि क्लाइंट सत्र स्थानीय रूप से उदाहरण # 1 में संग्रहीत किया गया है ।

इस समस्या से निपटने के लिए समाधान पाए गए हैं (जैसे सत्र प्रतिकृति और / या चिपचिपा सत्र को कॉन्फ़िगर करके), लेकिन REST आर्किटेक्चर एक और दृष्टिकोण का प्रस्ताव करता है: बस आप सर्वर को स्टेटफुल नहीं बनाते हैं, इसे स्टेटलेस बनाते हैं । क्षेत्ररक्षण के अनुसार :

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

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

कैसे?

एक सामान्य दृष्टिकोण एक टोकन-आधारित प्रमाणीकरण है , विशेष रूप से ट्रेंडी JSON वेब टोकन के साथ । ध्यान दें कि JWT में अभी भी कुछ मुद्दे हैं, विशेष रूप से समाप्ति के समय अमान्य और स्वत: प्रसार (यानी मुझे याद रखें सुविधा) से संबंधित।

साइड नोट्स

कुकीज़ या हेडर (या कुछ और) का उपयोग करने से कोई लेना-देना नहीं है कि सर्वर स्टेटस या स्टेटलेस है: ये सिर्फ मीडिया हैं जो यहां टोकन (स्टेटफुल सर्वर के लिए सत्र पहचानकर्ता, जेडब्ल्यूटी, आदि) के लिए उपयोग किए जाते हैं, और कुछ नहीं।

एक RESTful API केवल ब्राउज़र द्वारा प्रयोग किया जाता है, ( केवल Http और सुरक्षित ) कुकीज़ के रूप में ब्राउज़र स्वत: बाहर जाने वाले अनुरोध करने के लिए उन्हें संलग्न होगा काफी सुविधाजनक हो सकता है। यह ध्यान देने योग्य है कि यदि आप कुकीज़ का विकल्प चुनते हैं, तो CSRF से अवगत रहें (इसे रोकने का एक अच्छा तरीका यह है कि ग्राहक एक कुकी और एक कस्टम HTTP हेडर दोनों में समान विशिष्ट गुप्त मूल्य उत्पन्न करें और भेजें )।

सशर्त अनुरोधों के साथ उपलब्ध एपीआई

`Last-Modified` हेडर के साथ

सर्वर संसाधनों को पकड़ने वाली प्रतिक्रियाओं के लिए Last-Modified दिनांक शीर्षलेख प्रदान कर सकता है। ग्राहक को इस तिथि को संसाधन के साथ संग्रहीत करना चाहिए।

अब, हर बार जब ग्राहक संसाधन को पढ़ने के लिए एपीआई का अनुरोध करते हैं, तो वे अपने अनुरोधों में एक If-Modified-Since कर सकते हैं, जो कि उनके द्वारा प्राप्त और संग्रहित नवीनतम Last-Modified तारीख वाले हेडर हैं। सर्वर के पास अनुरोध के हेडर और संसाधन की वास्तविक अंतिम संशोधित तारीख की तुलना करने के लिए है। यदि वे समान हैं, तो सर्वर एक खाली शरीर के साथ एक 304 (नहीं संशोधित) लौटाता है: अनुरोध करने वाले ग्राहक को वर्तमान में कैश्ड संसाधन का उपयोग करना चाहिए।

इसके अलावा, जब ग्राहक संसाधन को अपडेट करने के लिए एपीआई का अनुरोध करते हैं (यानी एक असुरक्षित क्रिया के साथ), तो वे एक If-Unmodified-Since हेडर जोड़ सकते हैं। यह दौड़ की स्थिति से निपटने में मदद करता है: यदि हेडर और वास्तविक अंतिम संशोधित तिथि भिन्न होती है, तो सर्वर 412 (सटीक नाम) लौटाता है । क्लाइंट को तब संसाधन को संशोधित करने के लिए पुन: प्रयास करने से पहले संसाधन की नई स्थिति को पढ़ना चाहिए।

`ETag` हेडर के साथ

एक ETag (इकाई टैग) एक संसाधन की विशिष्ट स्थिति के लिए एक पहचानकर्ता है। यह एक मजबूत सत्यापन के लिए संसाधन का MD5 हैश, या कमजोर सत्यापन के लिए एक डोमेन-विशिष्ट पहचानकर्ता हो सकता है।

मूल रूप से, प्रक्रिया Last-Modified हेडर के साथ ही होती है: सर्वर उन संसाधनों को रखने वाली प्रतिक्रियाओं के लिए एक ETag हेडर प्रदान करता है, जो क्लाइंट को तब इस पहचानकर्ता को संसाधन के साथ मिलकर स्टोर करना चाहिए।

फिर, क्लाइंट जब वे संसाधन पढ़ना चाहते हैं, तो एक ई If-None-Match नो If-None-Match हेडर प्रदान करते हैं, जिसमें वे प्राप्त किए गए नवीनतम ईटाग होते हैं और संग्रहीत होते हैं। यदि शीर्ष लेख संसाधन के वास्तविक ETag से मेल खाता है, तो सर्वर अब 304 (संशोधित नहीं) लौटा सकता है।

जब वे संसाधन को संशोधित करना चाहते हैं, तो ग्राहक ईफ If-Match हेडर प्रदान कर सकते हैं, और यदि सर्वर ETAG वास्तविक से मेल नहीं खाता है, तो सर्वर को 412 (PRECONDITION FAILED) वापस करना होगा।

अतिरिक्त नोट्स

एताग> तारीख

यदि ग्राहक अपने अनुरोधों में दिनांक और ETag दोनों प्रदान करते हैं, तो तारीख को अनदेखा करना चाहिए। RFC 7232 से ( यहां और यहां ):

प्राप्तकर्ता जरूरी If-Modified-Since / if If-Unmodified-Since If-Modified-Since अनदेखा करता है If-Modified-Since If-Unmodified-Since अनुरोध में एक if If-Unmodified-Since If-None-Match / if If-Match हैडर फ़ील्ड शामिल होता है; If-None-Match / If-Match में If-Unmodified-Since If-Modified-Since If-Unmodified-Since If-Modified-Since / If-Unmodified-Since If-Modified-Since कंडीशन के लिए अधिक सटीक रिप्लेसमेंट माना जाता है, और इन दोनों को केवल पुराने साथियों के साथ इंटरऑपरेट करने के लिए जोड़ा जाता है। कि If-None-Match / If-Match लागू नहीं किया जा सकता है।

उथला ETAG

इसके अलावा, हालांकि यह काफी स्पष्ट है कि अंतिम संशोधित तिथियां संसाधन सर्वर-साइड के साथ बनी हुई हैं, ETag के साथ कई दृष्टिकोण उपलब्ध हैं।

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

ईटाग तंत्र का गहन कार्यान्वयन संभावित रूप से बहुत अधिक लाभ प्रदान कर सकता है - जैसे कि कैश से कुछ अनुरोधों की सेवा करना और गणना बिल्कुल नहीं करना - लेकिन कार्यान्वयन निश्चित रूप से सरल नहीं होगा, और न ही उथले दृष्टिकोण के रूप में प्लग करने योग्य होगा। यहाँ वर्णित है।

आम नुकसान

मुझे URL में क्रियाएं क्यों नहीं करनी चाहिए?

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

किसी संसाधन को आंशिक रूप से कैसे अपडेट करें?

जैसा कि PUT अनुरोध क्लाइंट को अपडेट किए गए मानों के साथ संपूर्ण संसाधन भेजने के लिए कहता है, PUT /users/123 उपयोग केवल उदाहरण के लिए किसी उपयोगकर्ता के ईमेल को अपडेट करने के लिए नहीं किया जा सकता है। जैसा कि विलियम डूरंड द्वारा कृपया समझाया गया है । एक बेवकूफ की तरह पैच मत करो। , कई अनुवर्ती समाधान उपलब्ध हैं:

संसाधन के गुणों को उजागर करें और एक अद्यतन मान भेजने के लिए PUT विधि का उपयोग करें, क्योंकि PUT विनिर्देश बताता है कि आंशिक सामग्री अद्यतन राज्य के साथ एक अलग पहचाने गए संसाधन को लक्षित करके संभव है जो बड़े संसाधन के एक हिस्से को ओवरलैप करता है :

PUT https://example.com/api/v1.2/users/123/email
body:
  new.email@example.com

PATCH अनुरोध का उपयोग करें जिसमें यह वर्णन करने का निर्देश शामिल हो कि संसाधन को कैसे संशोधित किया जाना चाहिए (जैसे JSON पैच का अनुसरण करना):

PATCH https://example.com/api/v1.2/users/123
body:
  [
    { "op": "replace", "path": "/email", "value": "new.email@example.com" }
  ]

मैट चैपमैन की टिप्पणी में प्रस्तावित संसाधन के आंशिक प्रतिनिधित्व वाले एक PATCH अनुरोध का उपयोग करें:

PATCH https://example.com/api/v1.2/users/123
body:
  {
    "email": "new.email@example.com"
  }

उन कार्यों के बारे में जो CRUD संचालन की दुनिया में फिट नहीं होते हैं?

एक व्यावहारिक उत्साहपूर्ण एपीआई डिजाइनिंग के लिए सर्वोत्तम प्रथाओं में विनय साहनी का उद्धरण:

यह वह जगह है जहां चीजें फजी हो सकती हैं। कई दृष्टिकोण हैं:
संसाधन के एक क्षेत्र की तरह प्रकट होने के लिए क्रिया का पुनर्गठन करें। यह काम करता है अगर कार्रवाई पैरामीटर नहीं लेती है। उदाहरण के लिए एक सक्रिय क्रिया को एक बूलियन activated क्षेत्र में मैप किया जा सकता है और एक PATCH के माध्यम से संसाधन में अद्यतन किया जा सकता है।
इसे Restful सिद्धांतों के साथ उप-संसाधन की तरह व्यवहार करें। उदाहरण के लिए, GitHub के एपीआई आप की सुविधा देता है एक सार स्टार के साथ PUT /gists/:id/star और अतारांकित के साथ DELETE /gists/:id/star ।
कभी-कभी आपके पास कार्रवाई को समझदार Restful संरचना में मैप करने का कोई तरीका नहीं होता है। उदाहरण के लिए, बहु-संसाधन खोज वास्तव में किसी विशिष्ट संसाधन के समापन बिंदु पर लागू होने के लिए समझ में नहीं आती है। इस मामले में, /search एक संसाधन नहीं होने के बावजूद सबसे अधिक समझ में आएगा। यह ठीक है - बस वही करें जो एपीआई उपभोक्ता के दृष्टिकोण से सही है और सुनिश्चित करें कि भ्रम से बचने के लिए इसे स्पष्ट रूप से प्रलेखित किया गया है।

आम प्रथाओं

एपीआई प्रलेखित है। आपके दस्तावेज़ बनाने में मदद करने के लिए उपकरण उपलब्ध हैं, जैसे स्वैगर या स्प्रिंग रेस्ट डॉक्स ।
API का संस्करण है , या तो हेडर के माध्यम से या URL के माध्यम से:

https://example.com/api/v1.2/blogs/123/articles
                        ^^^^

संसाधनों के बहुवचन नाम हैं :

https://example.com/api/v1.2/blogs/123/articles
                             ^^^^^     ^^^^^^^^

URL में कबाब-केस का उपयोग किया गया है (शब्दों को नीचा दिखाया गया है और डैश-अलग किया गया है):

https://example.com/api/v1.2/quotation-requests
                             ^^^^^^^^^^^^^^^^^^

HATEOAS स्वयं को लक्षित करते हुए, संसाधनों को "स्वयं" लिंक प्रदान करता है:

{
  ...,
  _links: {
    ...,
    self: { href: "https://example.com/api/v1.2/blogs/123/articles/789" }
    ^^^^
  }
}

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

{
  ...,
  _links: {
    ...,
    firstPage: { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=1&pageSize=25" }
    ^^^^^^^^^
  }
}

RESTful HTTP API के माध्यम से ब्लॉग प्रबंधन

निम्न उदाहरण HATEOAS को व्यक्त करने और उसका उपयोग करने के लिए HAL का उपयोग करते हैं:

CURIE (कॉम्पैक्ट यूआरआई): एपीआई प्रलेखन के लिंक प्रदान करने के लिए उपयोग किया जाता है
यूआरआई टेम्प्लेट : यूआरआई जिसमें पैरामीटर शामिल हैं जिन्हें यूआरआई हल करने से पहले प्रतिस्थापित किया जाना चाहिए

ब्लॉग 123 प्राप्त करें

निवेदन

GET https://example.com/api/v1.2/blogs/123
headers:
  Accept: application/hal+json

प्रतिक्रिया

status: 200 (OK)
headers:
  Content-Type: application/hal+json
body:
  {
    "id": 123,
    "title": "The blog title",
    "description": "The blog description",
    "_links": {
      "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
      "self": { "href": "https://example.com/api/v1.2/blogs/123" },
      "doc:articles": { "href": "https://example.com/api/v1.2/blogs/123/articles{?pageIndex,pageSize}", "templated": true }
    }
  }

ब्लॉग 123 में एक नया लेख बनाएँ

निवेदन

POST https://example.com/api/v1.2/blogs/123/articles
headers:
  Content-Type: application/json
  Accept: application/hal+json
  X-Access-Token: XYZ
body:
  {
    "title": "The title 2",
    "content": "The content 2"
  }

प्रतिक्रिया

status: 201 (CREATED)
headers:
  Content-Type: application/hal+json
body:
  {
    "id": 789,
    "title": "The title 2",
    "content": "The content 2",
    "_links": {
      "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
      "self": { "href": "https://example.com/api/v1.2/blogs/123/articles/789" },
      "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" },
      "doc:comments": { "href": "https://example.com/api/v1.2/blogs/123/articles/789/comments{?pageIndex,pageSize}", "templated": true }
    }
  }

ब्लॉग 123 के लेख 789 प्राप्त करें

निवेदन

GET https://example.com/api/v1.2/blogs/123/articles/789
headers:
  Accept: application/hal+json

प्रतिक्रिया

status: 200 (OK)
headers:
  Content-Type: application/hal+json
body:
  {
    "id": 789,
    "title": "The title 2",
    "content": "The content 2",
    "_links": {
      "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
      "self": { "href": "https://example.com/api/v1.2/blogs/123/articles/789" },
      "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" },
      "doc:comments": { "href": "https://example.com/api/v1.2/blogs/123/articles/789/comments{?pageIndex,pageSize}", "templated": true }
    }
  }

ब्लॉग 123 के 25 लेखों का 4 वां पेज प्राप्त करें

निवेदन

GET https://example.com/api/v1.2/blogs/123/articles?pageIndex=4&pageSize=25
headers:
  Accept: application/hal+json

प्रतिक्रिया

status: 200 (OK)
headers:
  Content-Type: application/hal+json
body:
  {
    "pageIndex": 4,
    "pageSize": 25,
    "totalPages": 26,
    "totalArticles": 648,
    "_link": {
      "firstPage": { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=1&pageSize=25" },
      "previousPage": { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=3&pageSize=25" },
      "self": { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=4&pageSize=25" },
      "nextPage": { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=5&pageSize=25" },
      "lastPage": { "href": "https://example.com/api/v1.2/blogs/123/articles?pageIndex=26&pageSize=25" }
    },
    "_embedded": [
      {
        ...
      }, {
        "id": 456,
        "title": "The title 1",
        "content": "The content 1",
        "_links": {
          "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
          "self": { "href": "https://example.com/api/v1.2/blogs/123/articles/456" },
          "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" },
          "doc:comments": { "href": "https://example.com/api/v1.2/blogs/123/articles/456/comments{?pageIndex,pageSize}", "templated": true }
        }
      }, {
        "id": 789,
        "title": "The title 2",
        "content": "The content 2",
        "_links": {
          "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
          "self": { "href": "https://example.com/api/v1.2/blogs/123/articles/789" },
          "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" },
          "doc:comments": { "href": "https://example.com/api/v1.2/blogs/123/articles/789/comments{?pageIndex,pageSize}", "templated": true }
        }
      }, {
        ...
      }
    ]
  }

ब्लॉग 123 का अद्यतन लेख 789

निवेदन

PUT https://example.com/api/v1.2/blogs/123/articles/789
headers:
  Content-Type: application/json
  Accept: application/hal+json
  X-Access-Token: XYZ
body:
  {
    "id": 789,
    "title": "The title 2 updated",
    "content": "The content 2 updated"
  }

प्रतिक्रिया

status: 200 (OK)
headers:
  Content-Type: application/hal+json
body:
  {
    "id": 789,
    "title": "The title 2 updated",
    "content": "The content 2 updated",
    "_links": {
      "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
      "self": { "href": "https://example.com/api/v1.2/blogs/123/articles/789" },
      "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" },
      "doc:comments": { "href": "https://example.com/api/v1.2/blogs/123/articles/789/comments{?pageIndex,pageSize}", "templated": true }
    }
  }

अद्यतन करने के लिए संसाधन की पहचान करने के लिए जिस पहचानकर्ता का उपयोग किया जाता है वह URL में एक है: शरीर में एक (यदि कोई हो) चुपचाप नजरअंदाज किया जाना चाहिए।
PUT अनुरोध पूरे संसाधन को अपडेट करता है, अगर कोई content नहीं भेजी जाती, तो उसे जारी संसाधन से हटा दिया जाना चाहिए था।

ब्लॉग 123 का लेख 789 हटाएं

निवेदन

DELETE https://example.com/api/v1.2/blogs/123/articles/789
headers:
  Accept: application/hal+json
  X-Access-Token: XYZ

प्रतिक्रिया

status: 204 (NO CONTENT)
headers:
  Content-Type: application/hal+json
body:
  {
    "_links": {
      "curies": [{ "name": "doc", "href": "https://example.com/docs/{rel}", "templated": true }],
      "doc:blog": { "href": "https://example.com/api/v1.2/blogs/123", "title": "The blog title" }
    }
  }

उल्लंघन करने वाले अन्य

<stock>
    <add>
        <item>
            <name>Milk</name>
            <quantity>2</quantity>
        </item>
    </add>
</stock>

इस बॉडी को रिसोर्स /stocks/123 जैसे संसाधन पर रखना REST के पीछे के विचार का उल्लंघन करता है। जबकि यह शरीर put और इसमें सभी प्रकार के परिशिष्ट शामिल होते हैं, यह शरीर को संसाधित करने पर कहीं न कहीं add लिए एक विधि कॉल के साथ भी आता है। REST के बाद item को /stocks/123/items/ पोस्ट किया जाएगा।

Modified text is an extract of the original Stack Overflow Documentation

के तहत लाइसेंस प्राप्त है CC BY-SA 3.0

से संबद्ध नहीं है Stack Overflow

टिप्पणियों

बाकी अवलोकन

HTTP पर REST

रिचर्डसन परिपक्वता मॉडल

HTTP अनुरोध और प्रतिक्रियाएँ

सामान्य HTTP प्रतिक्रिया स्थिति

सफलता

पुनर्निर्देशन

ग्राहक त्रुटियों

सर्वर त्रुटियों

टिप्पणियाँ

HATEOAS

मीडिया प्रकार

स्टेटलेस> स्टेटफुल

क्यों?

कैसे?

साइड नोट्स

सशर्त अनुरोधों के साथ उपलब्ध एपीआई

Last-Modified हेडर के साथ

ETag हेडर के साथ

अतिरिक्त नोट्स

एताग> तारीख

उथला ETAG

आम नुकसान

मुझे URL में क्रियाएं क्यों नहीं करनी चाहिए?

किसी संसाधन को आंशिक रूप से कैसे अपडेट करें?

उन कार्यों के बारे में जो CRUD संचालन की दुनिया में फिट नहीं होते हैं?

आम प्रथाओं

RESTful HTTP API के माध्यम से ब्लॉग प्रबंधन

ब्लॉग 123 प्राप्त करें

निवेदन

प्रतिक्रिया

ब्लॉग 123 में एक नया लेख बनाएँ

निवेदन

प्रतिक्रिया

ब्लॉग 123 के लेख 789 प्राप्त करें

निवेदन

प्रतिक्रिया

ब्लॉग 123 के 25 लेखों का 4 वां पेज प्राप्त करें

निवेदन

प्रतिक्रिया

ब्लॉग 123 का अद्यतन लेख 789

निवेदन

प्रतिक्रिया

टिप्पणियाँ

ब्लॉग 123 का लेख 789 हटाएं

निवेदन

प्रतिक्रिया

उल्लंघन करने वाले अन्य

`Last-Modified` हेडर के साथ

`ETag` हेडर के साथ