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

in ডিজাইনিং রেস্ট এপিআই,

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

"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 ইরর কোড ব্যবহার করা হয়। অর্থাৎ রিকোয়েস্ট এ কোন প্রকার পরিবর্তন না এনে ক্লায়েন্ট পুনরায় চেষ্টা করতে পারবে।

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

200 সব ঠিকঠাক আছে
201 সব ঠিক আছে এবং রিসোর্স তৈরী করা হয়েছে
304 ক্যাশ এ রাখা ডাটা এখনও অপরিবর্তিত আছে
400 রিকোয়েস্ট ডাটা বা ফরম্যাট ঠিক না
যেমন প্যারামিটার মিসিং, প্যারামিটার এর টাইপ ভুল দেয়া, ভুল এক্সেস টোকেন ইত্যাদি
401 অপারেশনটি করার জন্য আপনার অনুমতি নেই
403 কোন প্রকার অনুমতি কাজে দিবে না। আপনি রাস্তা মাপেন !
404 রিসোর্স খুজে পাওয়া যায়নি
405 মেথড গ্রহনযোগ্য নয়
500 ইন্টারনাল সার্ভার ইরর
503 এই মুহুর্তে সাভার রিকোয়েস্ট টি হ্যান্ড্যেল করতে পারছে না ।
সার্ভার ক্রাশ, মেইনটেনেন্স, ওভারলোড, ব্যাডন্ডওইথ সীমবদ্ধতা ইত্যাদি কারনে সার্ভিসটি একটিভ না

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

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

ইরর ডিজাইন   Invalid Request
ইরর ডিজাইন   An error occurred
ইরর ডিজাইন   Access token is required to complete this operation

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

কখনও কখনও একটি ইররের একধিক আলাদা কারন থাকতে পারে । সম্ভব হলে প্রত্যেকটি কারন কে একটি জেসন অবজেক্ট আলাদা করে একটি সম্পূর্ন এ্যারে রেসপন্স বডিতে রিটার্ন করুন। কিন্তু অনেক কন্ডিশন, কোড আর এক্সেপশন বেড়ে যাওয়ায় এটা বেশিরভাগ সময় সম্ভব হয়ে ওঠে না।

ইরর কোড

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

ইরর লিংক

 ইরর এর কারন সম্পর্কে বিস্তারিত জানার জন্য  ডকুমেন্টেশন লিংক প্রতিটি রেসপন্সের সাথে যুক্ত করে দিতে হবে। তবে ডকুমেন্টেশন না থাকলে এমন কোন সাপোর্ট লিংক দিন যেখানে ডেভেলপার এই ইররের সমাধান পাবে ।

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

{
"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]"
    }
}
পরবর্তী পোস্ট   »  ডিজাইনিং রেস্ট এপিআই [৫] : এপিআই ভার্সনিং


মুক্ত জ্ঞান ছড়িয়ে দিন সবার মাঝে!