API রেসপন্সে কোন কাঠামো ব্যবহার করবেন

মূল কথা: ফলাফল 4xx/5xx স্টেটাস কোডে প্রকাশ করুন, পেললোড { "data": ..., "meta": ... }-এ রাখুন, আর ব্যর্থতায় error এনভেলপে যান; অভ্যন্তরীণ API-তে এতটুকুই যথেষ্ট, আর কেবল বহু ইন্টিগ্রেটরযুক্ত পাবলিক প্ল্যাটফর্মে JSON:API বা OpenAPI দরকার।

আগে সবচেয়ে খারাপ বিকল্প বাদ দিন: সবসময় ২০০ ফেরত দিয়ে ফলাফল code ফিল্ডে রাখা।

তিন আকৃতি

A. খালি অবজেক্ট

复制{ "id": 1, "name": "demo", "price": 99 }

পরিচ্ছন্ন, আর HTTP সেমান্টিক্স কাজটা করে (404 মানে 404)। কিন্তু যেই পেজিনেশন, সতর্কতা বা trace id দরকার, চুক্তি না বদলে রাখার জায়গা নেই।

B. স্থিতিশীল এনভেলপ

复制{
  "data": { "id": 1, "name": "demo" },
  "meta": { "requestId": "abc", "took": 12 }
}

পেললোড ও মেটাডেটা আলাদা থাকে, তাই নতুন মেটাডেটা কখনো data-র আকৃতি বদলায় না। দাম এক স্তর নেস্টিং।

C. সবকিছু এনভেলপ (এড়ান)

复制{ "code": 0, "message": "success", "data": {...} }

আকৃতি পাপ নয়; অভ্যাসটি পাপ। প্রতিটি ফলাফলে ২০০ মানে CDN, গেটওয়ে, সার্কিট ব্রেকার, রিট্রাই নীতি ও ড্যাশবোর্ড — সবই সফলতা দেখে। তখন প্রতিটি অ্যালার্টে কাস্টম পার্সিং দরকার।

সুপারিশ

ফলাফলে HTTP স্টেটাস, পেললোডে এনভেলপ।

复制{
  "data": { "id": 1, "name": "demo" },
  "meta": { "requestId": "req_8f2a", "took": 12 }
}

复制{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "অর্ডার নেই বা মুছে ফেলা হয়েছে",
    "details": [{ "field": "id", "issue": "not_found" }]
  },
  "meta": { "requestId": "req_8f2a" }
}

স্টেটাস 4xx বা 5xx; code স্থিতিশীল ও মেশিন-পাঠযোগ্য; message মানুষের জন্য; details ফিল্ড-স্তরের ফর্ম এররের জন্য।

কঠোর নিয়ম

1. লিস্ট এন্ডপয়েন্টে পেজিনেশন মেটাডেটা থাকতেই হবে। total বা কার্সর ছাড়া পেজার নেই।
2. খালি লিস্ট [] ফেরত দেয়, কখনো null নয়। null.map বারবার ঘটে যাওয়া আউটেজ।
3. টাইমস্ট্যাম্প অফসেটসহ ISO 8601-এ। দেখুন টাইমস্ট্যাম্পের ফরম্যাট।
4. এক নামকরণ প্রথা। snake_case বা camelCase, সীমানায় একবার রূপান্তর।
5. টাকা ইন্টিজার উপ-একক বা স্ট্রিং হিসেবে। বাইনারি ফ্লোটিং পয়েন্টে 99.99 নিখুঁত নয়।
6. null-কে অনুপস্থিতের সঙ্গে গুলাবেন না। দেখুন null নাকি ফিল্ড বাদ।

কখন স্পেসিফিকেশন গ্রহণ করবেন

• বহু ইন্টিগ্রেটরযুক্ত পাবলিক প্ল্যাটফর্ম: JSON:API বা OpenAPI প্লাস ভাগ করা এনভেলপ
• একক-দলের অভ্যন্তরীণ API: উপরের এনভেলপই যথেষ্ট
• কঠোর চুক্তি: আগে Schema, তা থেকে কাঠামো জেনারেট

স্পেসিফিকেশন আলোচনা বাঁচায় আর অনবোর্ডিং খরচ নেয়। পাঁচজনের দলে JSON:API সাধারণত ঋণাত্মক কাজ।

সাধারণ প্রশ্ন

খালি অবজেক্ট ও এনভেলপের মধ্যে কীভাবে বাছাই করব?

পেজিনেশন, সতর্কতা বা requestId দরকার হলে এনভেলপ ব্যবহার করুন, যাতে meta বাড়তে পারে data-র আকৃতি না বদলিয়ে। কেবল যখন কোনো মেটাডেটা দরকার নেই আর পরে ফিল্ড যোগে চুক্তি বদলানো মেনে নিতে পারেন, তখন খালি অবজেক্ট ফেরান।

API কখনো প্রতিটি ফলাফলে ২০০ ফেরত দেওয়া উচিত নয় কেন?

CDN, গেটওয়ে, সার্কিট ব্রেকার, রিট্রাই নীতি ও ড্যাশবোর্ড — সবই HTTP স্টেটাস পড়ে ঠিক করে ক্যাশে করবে, রিট্রাই করবে বা অ্যালার্ট দেবে। সর্বত্র ২০০ থাকলে তারা ব্যর্থতাকে সফলতা ধরে, আর প্রতিটি অ্যালার্টে ব্যবসায়িক কোডের কাস্টম পার্সিং দরকার।

লিস্ট এন্ডপয়েন্টে পেজিনেশন মেটাডেটা থাকা উচিত?

হ্যাঁ। total বা কার্সর ছাড়া পেজার নেই, আর খালি লিস্টে null নয় [] ফেরত দিতে হবে, নাহলে ফ্রন্টএন্ডের .map কল ভাঙে।

আরও পড়ুন

• null নাকি ফিল্ড বাদ
• টাইমস্ট্যাম্পের ফরম্যাট