आरईएसटी एपीआई त्रुटि कोड वापसी संरचना

Question

मैं एक आरईएसटी एपीआई लिख रहा हूं और मैंने एक समस्या पर ठोकर खाई है। सत्यापन त्रुटियों को वापस करने का सबसे अच्छा तरीका क्या है।

अब तक मैं त्रुटि संदेश एक सामान्य त्रुटि कोड में फेंक दिया लौट रहे हैं

{ 
    "status": 400, 
    "error": { 
     "code": 1, // General bad request code 
     "message": [ 
       "The Key \"a\" is missing", 
       "The Key \"b\" is missing", 
       "The Key \"c\" is missing", 
       "Incorrect Format for field \"y\"" 
     ] 
    } 

) 

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

1. पहले का सामना करना पड़ा त्रुटि पर रोक और विशिष्ट त्रुटि कोड

   के साथ एक प्रतिक्रिया वापस

2. सभी अनुरोध डेटा पार्स और एकाधिक फ़ील्ड सत्यापन त्रुटियों को वापस करें।

   { 
       "status": 400, 
       "error": { 
       "code": 1 //General bad Request code 
       "message": "Bad Request", 
       "developer_message": "Field validation errors." 
       "more_info": "www.api.com/help/errors/1", 
       "error_details": { 
         0: { 
           "code": 2 // Specific field validation error code 
           "message": "Field \"x\" is missing from the array structure", 
           "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
           "more_info": "www.api.com/help/errors/2" 
          }, 
   
         1: { 
           "code": 3 // Specific field validation error code 
           "message": "Incorrect Format for field \"y\"", 
           "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
           "more_info": "www.api.com/help/errors/3" 
          } 
           } 
        } 
       } 
   

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

इसके अलावा मुझे लगता है कि विकल्प 1 अगर मैं स्क्रिप्ट के प्रवाह में एक भी गंभीर त्रुटि मिल अभी भी मान्य है। (नहीं सत्यापन त्रुटियों)

कृपया ध्यान दें कि कोड सिर्फ एक सरल सरणी सिर्फ इसलिए यह आसान है पीछा करना। प्रतिक्रिया प्रारूप जेएसओएन या एक्सएमएल होगा।

Answer 1

व्यक्तिगत रूप से मैं उपयोगकर्ताओं को कम विवरण देता हूं और या तो डेटाबेस लॉग तालिका या सिस्टम लॉग में डेवलपर्स को आवश्यक त्रुटियों को डंप करता हूं। इस तथ्य के कारण आप JSON का उपयोग कर रहे हैं और यह अपाचे सर्वर पर सबसे आम है और आपका कोड php होने की संभावना है (लेकिन घुंघराले ब्रेसिज़ के साथ आपका कोड उदाहरण PASCAL उदाहरण से उत्पन्न होने वाली कई भाषाओं हो सकता है जैसे सी, सी # PERL, PHP, सी तेज)। यहां बताया गया है कि सिस्टम लॉग में आउटपुट कस्टम त्रुटियों को कैसे रखा जाए यदि आप पहले से ही नहीं जानते कि php http://php.net/manual/en/function.syslog.php में कैसे। यदि आप JSON और CSharp के साथ एक दुर्लभ कॉन्फ़िगरेशन IIS का उपयोग कर रहे हैं तो .NET पुस्तकालय भी समान कार्य करने के लिए हैं। यदि आप किसी त्रुटि के दौरान अपने उपयोगकर्ताओं को बहुत अधिक जानकारी देते हैं तो आप भविष्य में एक हैकर भी अपनी वेबसाइट की जांच करने का एक तरीका दे रहे हैं।

Answer 2

मैंने # 2 स्वयं को दो बार उपयोग किया है। क्या यह # 1 से बेहतर है? मुझे लगता है कि इस पर निर्भर करता है कि आपके एपीआई का क्या उपयोग किया जा रहा है।

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

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

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

---

I would like to know if anyone went #2 and maybe have any improvements on it so I opened a bounty.

ज़रूर वहाँ किए जाने के लिए सुधार कर रहे हैं। जैसा कि है, शरीर में कुछ डेटा है जिसे छोड़ा जा सकता है।

{ 
    "status": 400, 
    "error": { 
    "code": 1 //General bad Request code 
    "message": "Bad Request", 
    "developer_message": "Field validation errors." 
    "more_info": "www.api.com/help/errors/1", 
    "error_details": { 
      0: { 
        "code": 2 // Specific field validation error code 
        "message": "Field \"x\" is missing from the array structure", 
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
        "more_info": "www.api.com/help/errors/2" 
       }, 

      1: { 
       (
        "code": 3 // Specific field validation error code 
        "message": "Incorrect Format for field \"y\"", 
        "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
        "more_info": "www.api.com/help/errors/3" 
       ) 
      } 
) 

HTTP प्रतिक्रियाओं के साथ, स्थिति कोड शरीर में नहीं जाना चाहिए, लेकिन शीर्षलेख में। इसका मतलब है कि "status": 400 और "message": "Bad Request" यहां छोड़ा जा सकता है। 400 प्रतिक्रिया का स्टेटस कोड होना चाहिए, और 400 का मतलब खराब अनुरोध होना चाहिए। यह एक HTTP मानक है और प्रतिक्रिया में समझाया जाना नहीं है। "developer_message": "Field validation errors." एक डुप्लिकेट है, क्योंकि प्रत्येक अलग त्रुटि में विशिष्ट त्रुटियां पहले ही शामिल हैं, इसलिए हम इसे छोड़ सकते हैं।

छोड़ देता है कि

{ 
    "error": { 
    "code": 1 //General bad Request code 
    "more_info": "www.api.com/help/errors/1", 
    "error_details": { 
      0: { 
        "code": 2 // Specific field validation error code 
        "message": "Field \"x\" is missing from the array structure", 
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
        "more_info": "www.api.com/help/errors/2" 
       }, 

      1: { 
       (
        "code": 3 // Specific field validation error code 
        "message": "Incorrect Format for field \"y\"", 
        "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
        "more_info": "www.api.com/help/errors/3" 
       ) 
      } 
) 

---

"code": 1 //General bad Request code 
"more_info": "www.api.com/help/errors/1", 

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

{ 
    "error": { 
    "error_details": { 
      0: { 
        "code": 2 // Specific field validation error code 
        "message": "Field \"x\" is missing from the array structure", 
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
        "more_info": "www.api.com/help/errors/2" 
       }, 

      1: { 
       (
        "code": 3 // Specific field validation error code 
        "message": "Incorrect Format for field \"y\"", 
        "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
        "more_info": "www.api.com/help/errors/3" 
       ) 
      } 
) 

400 स्थिति कोड पहले से ही इंगित करता है एक त्रुटि थी, ताकि आप डॉन ' टी को अब "error": {error details} इंगित करना होगा, क्योंकि हम पहले ही जानते हैं कि कोई त्रुटि हुई है। त्रुटियों की सूची बस रूट वस्तु बन कर सकते हैं:

[ 
    { 
     "code": 2//Specificfieldvalidationerrorcode 
     "message": "Field \"x\" is missing from the array structure", 
     "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
     "more_info": "www.api.com/help/errors/2" 
    }, 
    { 
     "code": 3//Specificfieldvalidationerrorcode 
     "message": "Incorrect Format for field \"y\"", 
     "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"", 
     "more_info": "www.api.com/help/errors/3" 
    } 
] 

तो सब है कि शरीर में बचा है अब बस त्रुटियों की एक सूची है।

स्थिति कोड प्रतिक्रिया शीर्षलेख में निर्दिष्ट है।
विवरण प्रतिक्रिया शरीर में निर्दिष्ट हैं।

Answer 3

सबसे पहले आप ग्राहकों के लिए बाकी API विधियों के लिए प्रलेखन प्रदान करते थे। तो यह पैरामीटर के लिए वैध डेटा प्रदान करने के लिए ग्राहक/डेवलपर से अपेक्षा की जाती है।

अब कहा गया है कि # 1 आराम API करने का सबसे अच्छा तरीका है। एक डेवलपर की ज़िम्मेदारी सर्वर के उपयोग को अधिकतम संभव सीमा तक कम करना है। तो यदि आपको कोई घातक त्रुटि आती है, तो संबंधित त्रुटि कोड और त्रुटि संदेश के साथ प्रतिक्रिया बनाएं और इसे वापस करें।

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

Answer 4

चलिए Facebook's Graph API पर देखें। यह मुश्किल से मारा जाता है, और बहुत अधिक त्रुटियों की संभावना अधिक होती है। यहां बताया गया है फेसबुक एक API त्रुटि पर रिटर्न है:

{ 
    "error": { 
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190, 
    "error_subcode": 460, 
    "error_user_title": "A title", 
    "error_user_msg": "A message" 
    } 
} 

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

नमूना त्रुटि प्रतिक्रियाएं:

{ 
    "error": { 
    "message": "(#200) Must have a valid access_token to access this endpoint", 
    "type": "OAuthException", 
    "code": 200 
    } 
} 

और

"error": { 
    "message": "(#604) Your statement is not indexable. The WHERE clause must contain 
    an indexable column. Such columns are marked with * in the tables linked from 
    http://developers.facebook.com/docs/reference/fql ", 
    "type": "OAuthException", 
    "code": 604 
} 

---

तो फिर वहाँ है JSend जो "एक विनिर्देश है कि वेब सर्वर से कैसे JSON प्रतिक्रिया के लिए कुछ नियम निर्धारित है चाहिए स्वरूपित किया जाना चाहिए। " उनका लक्ष्य है:

{ 
    "status" : "fail", 
    "data" : { "title" : "A title is required" } 
} 

यह फेसबुक की तरह लग रहा है और इस समूह एक उद्योग मानक की तरह स्थापित करने के लिए कोशिश कर रहा है अपनी पसंद # 1 के लिए चयन कर रहे हैं:

There are lots of web services out there providing JSON data, and each has its own way of formatting responses. Also, developers writing for JavaScript front-ends continually re-invent the wheel on communicating data from their servers. While there are many common patterns for structuring this data, there is no consistency in things like naming or types of responses. Also, this helps promote happiness and unity between backend developers and frontend designers, as everyone can come to expect a common approach to interacting with one another.

यहां एक नमूना त्रुटि संदेश है।

---

बाउंटी प्रश्न

के इनाम अनुरोध के जवाब में "अगर कोई # 2 चला गया और हो सकता है इस पर कोई सुधार नहीं है?", वहाँ Pragmatic RESTful API से एक डिजाइन पैटर्न है कि कहा गया है:

Validation errors will need a field breakdown. This is best modeled by using a fixed top-level error code for validation failures and providing the detailed errors in an additional errors field, like so:

{ 
    "code" : 1024, 
    "message" : "Validation Failed", 
    "errors" : [ 
    { 
     "code" : 5432, 
     "field" : "first_name", 
     "message" : "First name cannot have fancy characters" 
    }, 
    { 
     "code" : 5622, 
     "field" : "password", 
     "message" : "Password cannot be blank" 
    } 
    ] 
} 

Answer 5

मैंने हाल ही में एक रेस्ट एपीआई के खिलाफ काम किया है जो परिणामों में कई चेतावनियों या त्रुटियों को वापस करेगा। अपने नमूना # 2 से शुरू, मैं इसे इस प्रकार संशोधित करेगा:

{ 
    "status": 400, 
    "results" : null, 
    "warnings": { 
     0: { 
       // Build a warning message here, sample text to show concept 
       "code": 1 // Specific field validation error code 
       "message": "It is no longer neccessary to put .js on the URL" 
      } 
    } 
    "errors": { 
     0: { 
       "code": 2 // Specific field validation error code 
       "message": "Field \"x\" is missing from the array structure" 
       "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}", 
      }, 
     1: { 
       "code": 3 // Specific field validation error code 
       "message": "Incorrect Format for field \"y\"", 
       "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"" 
      } 
     } 
    } 

यह आपको परिणाम प्रदान करने के लिए कई चेतावनियों या त्रुटियों को अपने जवाब में की जरूरत के रूप में के साथ क्षमता प्रदान करेगा।

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

मैं भी करने के बजाय हर त्रुटि को IMHO वे एपीआई डॉक्स (कैसे एक त्रुटि कोड का उपयोग कर मदद खोजने के लिए) में होना चाहिए निम्नलिखित मदों को दूर होगा:,

"more_info": "www.api.com/help/errors/2" 
"more_info": "www.api.com/help/errors/3" 

उन्हीं पंक्तियों के साथ मैं ' मुझे यकीन नहीं है कि आपको संदेश और developer_message दोनों की आवश्यकता है या नहीं। वे अनावश्यक प्रतीत होते हैं और जैसे कि आप API से उपयोगकर्ता त्रुटि संदेश प्रदान करने का प्रयास कर रहे हैं जब कॉलर डेटा को सही तरीके से प्रदान करने में विफल रहा।

Answer 6

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