HTTP
एपीआई के लिए HTTP

टिप्पणियों

एक संसाधन बनाएँ

हर कोई इस बात पर सहमत नहीं है कि संसाधन निर्माण के लिए सबसे अधिक सही तरीका क्या है। इस प्रकार, आपका API POST या PUT अनुरोध स्वीकार कर सकता है, या तो।

यदि सर्वर सफलतापूर्वक बनाया गया था, तो सर्वर को 201 Created साथ प्रतिक्रिया करनी चाहिए। सबसे उपयुक्त त्रुटि कोड चुनें यदि यह नहीं था।

उदाहरण के लिए, यदि आप कर्मचारी रिकॉर्ड बनाने के लिए एपीआई प्रदान करते हैं, तो अनुरोध / प्रतिक्रिया इस तरह दिख सकती है:

POST /employees HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "Charlie Smith",
    "age": 38,
    "job_title": "Software Developer",
    "salary": 54895.00
}

HTTP/1.1 201 Created
Location: /employees/1/charlie-smith
Content-Type: application/json

{
    "employee": {
        "name": "Charlie Smith",
        "age": 38,
        "job_title": "Software Developer",
        "salary": 54895.00
        "links": [
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "self",
                "method": "GET"
            },
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "delete",
                "method": "DELETE"
            },
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "edit",
                "method": "PATCH"
            }
        ]
    },
    "links": [
        {
            "uri": "/employees",
            "rel": "create",
            "method": "POST"
        }
    ]
}

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

एक संसाधन संपादित करें

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

यदि अपडेट किया गया था, तो आपके सर्वर को 200 OK साथ जवाब देना चाहिए, या यदि इसे अभी तक लागू किया जाना है, तो 202 Accepted । यदि इसे पूरा नहीं किया जा सकता है तो सबसे उपयुक्त त्रुटि कोड चुनें।

पूर्ण अपडेट

PUT में अनुरोध में शामिल पेलोड के साथ वर्तमान प्रतिनिधित्व को बदलने का शब्दार्थ है। यदि पेलोड समान प्रतिनिधित्व प्रकार का नहीं है जो अद्यतन करने के लिए संसाधन के वर्तमान प्रतिनिधित्व के रूप में है, तो सर्वर यह तय कर सकता है कि किस दृष्टिकोण को लेना है। RFC7231 परिभाषित करता है कि सर्वर या तो कर सकता है

• नए मीडिया प्रकार को प्रतिबिंबित करने के लिए लक्ष्य संसाधन को पुन: कॉन्फ़िगर करें
• नई संसाधन स्थिति के रूप में सहेजने से पहले रिज़ॉर्ट के अनुरूप एक प्रारूप में PUT प्रतिनिधित्व बदलें
• 415 Unsupported Media Type प्रतिक्रिया के साथ अनुरोध को अस्वीकार करें, यह दर्शाता है कि लक्ष्य संसाधन मीडिया प्रकारों के एक विशिष्ट (सेट) तक सीमित है।

एक बेस संसाधन जिसमें JSON HAL प्रतिनिधित्व होता है जैसे ...

{
    "name": "Charlie Smith",
    "age": 39,
    "job_title": "Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    }
}

... इस तरह एक अद्यतन अनुरोध प्राप्त हो सकता है

PUT /users/1234 HTTP/1.1
Host: http://www.acmee.com
Content-Type: "application/json; charset=utf-8"
Content-Length: 85
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer"
}

सर्वर अब दिए गए अनुरोध निकाय के साथ संसाधन की स्थिति को बदल सकता है और सामग्री / प्रकार को application/hal+json से application/json भी बदल सकता है या JSON पेलोड को JSON HAL प्रतिनिधित्व में बदल सकता है और फिर संसाधन की सामग्री को बदल सकता है। रूपांतरित एक के साथ या 415 Unsupported Media Type प्रतिक्रिया के साथ एक अक्षम मीडिया प्रकार के कारण अद्यतन अनुरोध को अस्वीकार करें।

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

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer"
}

जबकि परिवर्तन और फिर दृष्टिकोण की जगह निम्नलिखित प्रतिनिधित्व लौटाएगा:

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: e0023aa4e

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    }
}

दुष्प्रभाव

ध्यान दें कि PUT को साइड-इफ़ेक्ट्स की अनुमति है, हालांकि इसे इम्पोटेंट ऑपरेशन के रूप में परिभाषित किया गया है! यह RFC7231 के रूप में प्रलेखित है

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

अतिरिक्त लॉग प्रविष्टियों का उत्पादन आमतौर पर साइड इफेक्ट के रूप में नहीं माना जाता है क्योंकि यह निश्चित रूप से सामान्य रूप से संसाधन की कोई स्थिति नहीं है।

आंशिक अद्यतन

RFC7231 में आंशिक अपडेट के बारे में इसका उल्लेख है:

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

इसलिए आंशिक अद्यतन दो स्वादों में किए जा सकते हैं:

• एक संसाधन कई छोटे उप-संसाधनों को एम्बेड करें और PUT माध्यम से पूर्ण संसाधन के बजाय केवल एक संबंधित उप-संसाधन को अपडेट करें
• PATCH का उपयोग करना और सर्वर को अपडेट करने के लिए निर्देश देना

अतिव्यापी राज्य के साथ आंशिक अद्यतन

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

इस कदम से पहले एक उपयोगकर्ता के पास निम्न प्रतिनिधित्व था

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept: application/hal+json; charset=utf-8
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    },
    "_embedded": {
        "ea:address": {
            "street": "Terrace Drive, Central Park",
            "zip": "NY 10024"
            "city": "New York",
            "country": "United States of America",
            "_links": {
                "self": { "href": "/address/abc" },
                "google_maps": { "href": "http://maps.google.com/?ll=40.7739166,-73.970176" }
            }
        }
    }
}

जैसे ही उपयोगकर्ता एक नए स्थान पर जा रहा है, वह अपनी स्थान जानकारी को इस तरह से अपडेट करता है:

PUT /address/abc HTTP/1.1
Host: http://www.acmee.com
Content-Type: "application/json; charset=utf-8"
Content-Length: 109
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

{
    "street": "Standford Ave",
    "zip": "CA 94306",
    "city": "Pablo Alto",
    "country": "United States of America"
}

मौजूदा पता संसाधन और अनुरोध में एक के बीच बेमेल मीडिया-प्रकार के लिए परिवर्तन-पहले-प्रतिस्थापित अर्थ के साथ, जैसा कि ऊपर वर्णित है, पता संसाधन अब अपडेट किया गया है जिसका प्रभाव उपयोगकर्ता संसाधन पर बाद में GET अनुरोध पर है उपयोगकर्ता के लिए नया पता वापस आ गया है।

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept: application/hal+json; charset=utf-8
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    },
    "_embedded": {
        "ea:address": {
            "street": "Standford Ave",
            "zip": "CA 94306",
            "city": "Pablo Alto",
            "country": "United States of America"
            "_links": {
                "self": { "href": "/address/abc" },
                "google_maps": { "href": "http://maps.google.com/?ll=37.4241311,-122.1524475" }
            }
        }
    }
}

आंशिक डेटा पैचिंग

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

PATCH विधि अनुरोध करती है कि अनुरोध इकाई में वर्णित परिवर्तनों का एक सेट अनुरोध-यूआरआई द्वारा पहचाने गए संसाधन पर लागू हो। परिवर्तनों के सेट को एक मीडिया प्रकार द्वारा पहचाने जाने वाले "पैच दस्तावेज़" नामक प्रारूप में दर्शाया गया है।

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

पैचिंग के लिए एक लोकप्रिय JSON आधारित मीडिया-प्रकार JSON पैच है ।

यदि हमारे नमूना उपयोगकर्ता की आयु और नौकरी-शीर्षक में परिवर्तन होता है और उपयोगकर्ता की आय का प्रतिनिधित्व करने वाला एक अतिरिक्त क्षेत्र जोड़ा जाना चाहिए, तो JSON पैच का उपयोग करके PATCH का उपयोग करके आंशिक अद्यतन जोड़ा जा सकता है:

PATCH /users/1234 HTTP/1.1
Host: http://www.acmee.com
Content-Type: application/json-patch+json; charset=utf-8
Content-Length: 188
Accept: application/json
If-Match: "e0023aa4e"

[
    { "op": "replace", "path": "/age", "value": 40 },
    { "op": "replace", "path": "/job_title", "value": "Senior Software Developer" },
    { "op": "add", "path": "/salery", "value": 63985.00 }
]

PATCH एक साथ कई संसाधनों को अपडेट कर सकती है और परिवर्तनों को एटोमिक रूप से लागू करने की आवश्यकता होती है जिसका अर्थ है कि या तो सभी परिवर्तनों को लागू करना है या कोई भी ऐसा नहीं है जो एपीआई कार्यान्वयनकर्ता पर लेन-देन का बोझ डालता है।

एक सफल अपडेट कुछ इस तरह वापस आ सकता है

HTTP/1.1 200 OK
Location: /users/1234
Content-Type: application/json
ETag: "df00eb258"

{
    "name": "Charlie Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "salary": 63985.00
}

हालांकि केवल 200 OK रिस्पांस कोड तक ही सीमित नहीं है।

ETag -इन अपडेट (रिप्रेजेंटेशन स्टेट के पिछले ETag बीच में किए गए बदलाव और अपडेट) को ETag , If-Match या If-Unmodified-Since हेडर का इस्तेमाल किया जाना चाहिए।

गलती संभालना

PATCH पर युक्ति निम्नलिखित त्रुटि से निपटने की सिफारिश करती है:

एक संसाधन हटाएं

HTTP APIs का एक अन्य सामान्य उपयोग मौजूदा संसाधन को हटाना है। यह आमतौर पर DELETE अनुरोधों का उपयोग करके किया जाना चाहिए।

यदि विलोपन सफल रहा, तो सर्वर को 200 OK वापस करना चाहिए; एक उपयुक्त त्रुटि कोड अगर यह नहीं था।

यदि हमारे कर्मचारी चार्ली स्मिथ ने कंपनी छोड़ दी है और हम अब उसके रिकॉर्ड को हटाना चाहते हैं, तो वह इस तरह दिख सकता है:

DELETE /employees/1/charlie-smith HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
    'links': [
        {
            'uri': '/employees',
            'rel': 'create',
            'method': 'POST'
        }
    ]
}

सूची संसाधन

HTTP एपीआई का अंतिम आम उपयोग सर्वर पर मौजूदा संसाधनों की एक सूची प्राप्त करना है। इस तरह की सूची GET अनुरोधों का उपयोग करके प्राप्त की जानी चाहिए, क्योंकि वे केवल डेटा प्राप्त करते हैं।

यदि यह सूची, या उपयुक्त त्रुटि कोड की आपूर्ति कर सकता है तो सर्वर को 200 OK वापस करना चाहिए।

हमारे कर्मचारियों की सूची, फिर, इस तरह लग सकता है:

GET /employees HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
    'employees': [
        {
            'name': 'Charlie Smith',
            'age': 39,
            'job_title': 'Software Developer',
            'salary': 63985.00
            'links': [
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'self',
                    'method': 'GET'
                },
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'delete',
                    'method': 'DELETE'
                },
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'edit',
                    'method': 'PATCH'
                }
            ]
        },
        {
            'name': 'Donna Prima',
            'age': 30,
            'job_title': 'QA Tester',
            'salary': 77095.00
            'links': [
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'self',
                    'method': 'GET'
                },
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'delete',
                    'method': 'DELETE'
                },
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'edit',
                    'method': 'PATCH'
                }
            ]
        }
    ],
    'links': [
        {
            'uri': '/employees/new',
            'rel': 'create',
            'method': 'PUT'
        }
    ]
}