मानक JSON एपीआई प्रतिक्रिया प्रारूप?




request response (8)

एपीआई से JSON प्रतिक्रियाओं को संरचित करने के लिए मानक या सर्वोत्तम प्रथाएं मौजूद हैं? जाहिर है कि प्रत्येक एप्लिकेशन का डेटा अलग होता है, इसलिए यदि आप चाहें तो "प्रतिक्रिया बॉयलरप्लेट" के बजाय, मैं जितना अधिक चिंतित नहीं हूं। मेरा क्या मतलब है इसका एक उदाहरण:

सफल अनुरोध:

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

विफल अनुरोध:

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}

Google JSON मार्गदर्शिका

सफलता प्रतिक्रिया वापसी data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

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

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

और यदि आपका ग्राहक जेएस है, तो आप if ("error" in response) {} का उपयोग कर सकते हैं यह जांचने के लिए कि क्या त्रुटि है या नहीं।


JSON का बिंदु यह है कि यह पूरी तरह गतिशील और लचीला है। इसे जो कुछ भी आप चाहते हैं उसे झुकाएं, क्योंकि यह केवल एक नोड में रूट किए गए क्रमबद्ध जावास्क्रिप्ट ऑब्जेक्ट्स और सरणी का एक सेट है।

रूटनोड का प्रकार आपके ऊपर है, इसमें क्या शामिल है, आप प्रतिक्रिया के साथ मेटाडेटा भेजते हैं, चाहे आप माइम-टाइप को application/json सेट करें या इसे text/plain आप पर निर्भर करता है (जब तक आप किनारे के मामलों को संभालने के बारे में जानते हैं)।

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

तो आखिरी चीज जो मैं चाहूंगा, वह सब करने पर, प्रत्येक को एक ही बॉयलरप्लेट मानक के अनुरूप बनाने की कोशिश करना है, जो XML2.0 या somesuch पर आधारित है।

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


इसके लायक होने के लिए मैं इसे अलग करता हूं। एक सफल कॉल में सिर्फ JSON ऑब्जेक्ट्स हैं। मुझे उच्च स्तर की JSON ऑब्जेक्ट की आवश्यकता नहीं है जिसमें एक सफल फ़ील्ड है जो सत्य और एक पेलोड फ़ील्ड इंगित करता है जिसमें JSON ऑब्जेक्ट है। मैं सिर्फ 200 के साथ उचित JSON ऑब्जेक्ट को वापस भेजता हूं या शीर्षलेख में HTTP स्थिति के लिए 200 रेंज में जो कुछ भी उचित है।

हालांकि, अगर कोई त्रुटि है (400 परिवार में कुछ) मैं एक अच्छी तरह से गठित JSON त्रुटि ऑब्जेक्ट देता हूं। उदाहरण के लिए, यदि ग्राहक किसी ईमेल पते और फोन नंबर के साथ उपयोगकर्ता को पोस्ट कर रहा है और इनमें से एक विकृत है (यानी मैं इसे अपने अंतर्निहित डेटाबेस में नहीं डाल सकता) तो मैं इस तरह कुछ वापस कर दूंगा:

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

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

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

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

एक चीज जिसे मैंने जोड़ने के बारे में सोचा था, वह "त्रुटियों" सरणी प्रविष्टियों या JSON ऑब्जेक्ट की जड़ में एक संख्यात्मक त्रुटि कोड था। लेकिन अब तक हमें इसकी आवश्यकता नहीं है।


जेसन प्रारूप Instagram का उपयोग कर रहा है

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}

मुझे लगता है कि एक डिफैक्टो मानक वास्तव में उभरा नहीं है (और कभी नहीं)। लेकिन परवाह किए बिना, मेरा लेना है:

सफल अनुरोध:

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

विफल अनुरोध:

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

लाभ: सफलता और त्रुटि दोनों मामलों में समान शीर्ष स्तर के तत्व

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


मैं दावा करने के लिए घमंडी नहीं होगा कि यह एक मानक है इसलिए मैं "मैं पसंद करता हूं" फॉर्म का उपयोग करूंगा।

मैं terse प्रतिक्रिया पसंद करते हैं (जब लेखों की एक सूची का अनुरोध करते हैं तो मैं लेखों की एक JSON सरणी चाहता हूं)।

मेरे डिज़ाइन में मैं स्टेटस रिपोर्ट के लिए HTTP का उपयोग करता हूं, 200 रिटर्न केवल पेलोड देता है।

400 अनुरोध के साथ गलत क्या है इसका एक संदेश देता है:

{"message" : "Missing parameter: 'param'"}

मॉडल / नियंत्रक / यूआरआई मौजूद नहीं है तो 404 लौटें

अगर मेरी तरफ से प्रसंस्करण में कोई त्रुटि हुई, तो मैं एक संदेश के साथ 501 लौटाता हूं:

{"message" : "Could not connect to data store."}

मैंने जो कुछ देखा है उससे कुछ आरईएसटी-आश ढांचे इन लाइनों के साथ होते हैं।

तर्क :

JSON को एक पेलोड प्रारूप माना जाता है, यह सत्र प्रोटोकॉल नहीं है। वर्बोज सत्र-आश पेलोड का पूरा विचार एक्सएमएल / एसओएपी दुनिया से आता है और विभिन्न गुमराह किए गए विकल्पों ने उन ब्लोएटेड डिज़ाइनों को बनाया है। हमें एहसास हुआ कि यह सब एक बड़ा सिरदर्द था, आरईएसटी / जेएसओएन का पूरा बिंदु इसे किस करना था, और HTTP का पालन करना था। मुझे नहीं लगता कि जेएसएंड में कुछ भी दूरस्थ रूप से मानक है और विशेष रूप से उनमें से अधिक वर्बोज़ के साथ नहीं। एक्सएचआर HTTP प्रतिक्रिया पर प्रतिक्रिया करेगा, अगर आप अपने AJAX (जैसे अधिकांश करते हैं) के लिए jQuery का उपयोग करते हैं तो आप त्रुटियों को कैप्चर करने के लिए try / catch और done() / fail() कॉलबैक का उपयोग कर सकते हैं। मैं नहीं देख सकता कि JSON में स्थिति को कैसे समाशोधन करना उससे कहीं अधिक उपयोगी है।


JSON-RPC 2.0 मानक अनुरोध और प्रतिक्रिया प्रारूप को परिभाषित करता है, और आरईएसटी एपीआई के साथ काम करने के बाद ताजा हवा का सांस है।






response