ডিজাইনিং রেস্ট এপিআই [৪] : ইরর ডিজাইন

আমরা অনেক ধৈর্য আর যত্ন সহকারে কোড করি কিন্তু দুর্ভাগ্যবশত সবসময় কিছু না কিছু ভুল থেকেই যায় । সিস্টেমটির যেভাবে কাজ করার কথা ছিল সেভাবে কেন কাজ করছে না এর উত্তর তখন আমাদের কাছে অনেক মূল্যবান । আর রেস্ট এর ক্লায়েন্ট এ্যাপ্লিকেশন ডেভেলপারদের কাছে এই উত্তর টা বের করা মোটামুটি এভারেস্ট জয়ের মত। কারন তারা শুধুমাত্র আপনার এপিআই কিভাবে ব্যবহার করতে হবে তার একটি নিয়মকানুন ব্যতিত এপিআই এর ভিতরকার আচরনবিধি কিছুই জানে না। উদাহরন হিসেবে ধরুন আপনি ফেসবুক এপিআই তে একটি জটিল কোয়েরী রিকোয়েস্ট করলেন আর ফেসবুক রেসপন্স করল:

"error" : "An error occurred"

এই একটি লাইন মেসেজ থেকে আপনি কিভাবে বুঝবেন আপনার ভুলটা কোথায়? যদি ফেসবুকের অফিশিয়াল সাইটে যদি আপনি এর কারন খুজে নাও পান তবে একটু খোজাখুজি করলে বিভিন্ন ফোরাম বা স্ট্যাকওভারফ্লোতে এর উত্তর পাবেনই । কিন্তু এটা যদি ফেসবুক না হয়ে নতুন একটি এপিআই হত তাহলে এর উত্তর খুজতে আপনার হয়ত কয়েক দিন লেগে যেত । কিন্তু এপিআই যদি আরেকটু সুন্দর ভাবে ইররটি রিটার্ন করত :

"error" : "Invalid Access Token"
"details": "The token is not valid or expired.Also check the timestamp"
"link" : "http://host.com/api/documentation/invalid-access-token.html"

উপরের রেসপন্সটি দেখে আমি সহজেই বুঝতে পারি ভুলটি কোথায় । আর তাতেও যদি সমস্যা সমাধান না হয় তাহলে লিংকটি থেকে বিস্তারিত কারন দেখে সমস্যা সমাধান কোন ব্যাপার না।

সুতরাং এপিআই কনজিউমারদের ইরর হ্যান্ডলিং এর জন্য আপনাকে বলে দিতে হবে কোথায় কেন ইরর ঘটল। তাহলে এখন আমরা দেখব আমাদের ইরর ডিজাইন কেমন হওয়া উচিত।

HTTP স্ট্যাটাস কোডের সঠিক ব্যবহার

HTTP স্ট্যাটাস কোড একটি স্ট্যান্ডার্ড মডেল এবং ক্লায়েন্ট এ্যাপ্লিকেশন এটি খুব সহজেই হ্যান্ডেল করতে পারে। সকল রিকোয়েস্ট এর জন্য ঢালাওভাবে 200 [OK] রিটার্ন না করে প্রতিটি রিকোয়েস্ট এর জন্য সামঞ্জস্যপূর্ন কোড ব্যবহার করতে হবে ।  সফলভাবে রিকোয়েস্ট এক্সিকিউট হলে 2xx স্ট্যাটাস কোড রিটার্ন করবেন । আর তা না কোন কারনে রিকোয়েস্ট ফেইল করল তা যতটা সঠিক এবং  স্পষ্ট করে রিটার্ন করতে হবে। এক্ষেত্রে মনে রাখতে হবে যে ইরর দুটি কারনে হয় :

১। 4xx ক্লায়েন্ট ইরর – এপিআই ক্লায়েন্ট ভুল ভাবে রিকোয়েস্ট সেন্ড করেছে। ক্লায়েন্ট এর রিকোয়েস্ট এ কোন ভুল থাকলে 4xx ইরর কোড ব্যবহার করা হয় । অর্থাৎ একই রিকোয়েস্ট বারবার  না করে বরং ভুলটি সুধরে পুনরায় রিকোয়েষ্ট করতে হবে।

২। 5xx সার্ভার ইরর – রিকোয়েস্ট হ্যান্ডেল করতে সার্ভার ব্যার্থ হয়েছে । সার্ভার ইন্টারনাল কোন কারনে রিকোয়েস্ট প্রসেস করতে ব্যর্থ হলে 5xx ইরর কোড ব্যবহার করা হয়। অর্থাৎ রিকোয়েস্ট এ কোন প্রকার পরিবর্তন না এনে ক্লায়েন্ট পুনরায় চেষ্টা করতে পারবে।

নিচে রেস্ট এপিআই এর সবচেয়ে কমন ১০টি স্ট্যাটাস কোড দেয়া হল, সম্পূর্ন লিস্ট দেখতে উইকিপিডায়া দেখুন-

বর্ননামূলক ইরর মেজেস

মনে রাখতে হবে যে এন্ড ইউজার এবং ক্লায়েন্ট ডেভেলপার দুজনই আপনার এপিআই এর ইউজার । এন্ড ইউজার এর জন্য ছোট একটি মেসেজ যথেষ্ট। আর ডেভেলপারদের ডিবাগের জন্য যত বেশি তথ্য দেয়া যায় ততই ভাল। যদি ক্লায়েন্ট ডেভেলপার ইরর এর কোন সমাধান না করতে পারে তাহলে সেটা আপনার জন্য কখনই সুখকর না । আপনি তখন অনেক সময় নিয়ে খুজে খুজে দেখবেন আপনার সিস্টেমে কোন ইরর গুলো বেশি হয়, কেন হয় । এপিআই কে রিলায়েবল রাখতে আপনার ইরর ডিজাইন অবশ্যই ভাল হতে হবে । অর্থাৎ কি ঘটল, কেন ঘটল এবং সবচেয়ে গুরুত্বপূর্ন হল কিভাবে সমাধান করতে হবে তা ডেভেলপাররে কাছে সুন্দর ভাবে উপস্থাপন করতে হবে।

  Invalid Request
  An error occurred
  Access token is required to complete this operation

একাধিক ইরর মেসেজ

ইরর কোড

ইরর লিংক

একটি আদর্শ ইরর ডিজাইন

{
"status":400,
 "error" : 
   {
    "code" : "E9081",
    "message" : "Access token required",
    "description":"Access token is required to complete this operation.",
    "link" : "http://host.com/docs/errors/e9081/"
   }
}

উদহরনে একটি ছোট ইররকে প্রেজেন্ট করা হয়েছে এভাবে:

• status: 400 অর্থাৎ ক্লায়েন্ট এর কোন ভুলের কারনে রিকোয়েস্ট সফল হয়নি ।
• message: সেই ভুলটি টি ছোট করে বলা হয়েছে । এই ধরনের মেসেজ সাধারনত পপআপ বা ডায়ালগে বেশি ব্যবহৃত হয় ।
• description: এখানে ভুলের কারন এক বা একধিক লাইনে ডেভেলপারদের জন্য বর্ননা করা হয়।
• code: উক্ত ইররকে আলাদাভাবে চিহ্নিত করার জন্য একটি কাস্টম কোড E9081 দেয়া হয়েছে ।
• link: ইরর E9081 এর কারন এবং সমাধানের জন্য ডকুমেন্টেশন লিংক দেয়া আছে।

 শেষ করার পূর্বে গুগলের একটি ইরর রেসপন্স দেখে নেই

{"error": 
    {"errors": 
      [
        {
          "domain": "global",
          "reason": "invalidParameter",
          "message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000],
          "locationType": "parameter","location": "max-results"
        }
      ],

    "code": 400,
    "message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]"
    }
}