কিভাবে Idempotent এবং Versioned REST API ডিজাইন করবেন

আপনি একটি নতুন ফিচার ডিপ্লয় করলেন, এবং হঠাৎ আপনার API টাইমআউটের পরে রিট্রাই করা ক্লায়েন্টদের কাছ থেকে ডুপ্লিকেট POST রিকোয়েস্ট পেতে শুরু করল। আপনার ডেটাবেসে এখন দুটি অভিন্ন অর্ডার আছে। অথবা আপনি একটি ব্রেকিং চেঞ্জ রোল আউট করলেন, এবং মোবাইল অ্যাপগুলো ক্র্যাশ করছে কারণ তারা পুরনো রেসপন্স ফরম্যাট আশা করেছিল। এগুলো API ডিজাইনের দুটি সবচেয়ে সাধারণ এবং যন্ত্রণাদায়ক সমস্যা: non-idempotent অপারেশন এবং ব্রেকিং চেঞ্জ। এই গাইডটি আপনাকে দেখাবে কিভাবে REST API-তে idempotency এবং versioning-এর ব্যবহারিক প্যাটার্ন দিয়ে উভয়ই সমাধান করা যায়।

REST API-তে Idempotency কেন গুরুত্বপূর্ণ

Idempotency মানে একই রিকোয়েস্ট একাধিকবার করলে একবার করার মতোই একই ফলাফল পাওয়া যায়। HTTP মেথডগুলোর নির্দিষ্ট idempotency সেমান্টিক্স রয়েছে: GET, HEAD, PUT, DELETE, এবং OPTIONS idempotent, কিন্তু POST এবং PATCH নয়। তবে বাস্তব-জগতের API-গুলো প্রায়ই রিসোর্স তৈরি বা পেমেন্ট প্রসেসিংয়ের মতো অপারেশনের জন্য POST গ্রহণ করতে হয়। নেটওয়ার্ক ব্যর্থতা, ক্লায়েন্ট টাইমআউট, এবং রিট্রাই লজিক ডুপ্লিকেট সৃষ্টি করতে পারে। Idempotency ছাড়া, আপনি ডাবল চার্জ, ডুপ্লিকেট রেকর্ড, বা অসঙ্গত স্টেটের ঝুঁকিতে পড়েন।

Idempotent REST API-এর কৌশল

১. POST রিকোয়েস্টের জন্য Idempotency Key ব্যবহার করুন

সবচেয়ে সাধারণ পদ্ধতি হলো ক্লায়েন্টদের একটি Idempotency-Key হেডারে একটি অনন্য কী (যেমন একটি UUID) পাঠাতে দেওয়া। সার্ভার কী এবং অপারেশনের ফলাফল সংরক্ষণ করে। যদি একই কী আবার পাওয়া যায়, সার্ভার অপারেশন পুনরায় চালানোর পরিবর্তে সংরক্ষিত ফলাফল ফেরত দেয়।

POST /payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "amount": 1000,
  "currency": "USD"
}

ইমপ্লিমেন্টেশন ধাপ:

1. ক্লায়েন্ট প্রতিটি লজিক্যাল অপারেশনের জন্য একটি অনন্য কী (UUID v4) তৈরি করে।
2. সার্ভার চেক করে কীটি একটি স্থায়ী স্টোর (যেমন Redis বা ডেটাবেস) এ আছে কিনা।
3. যদি না থাকে, রিকোয়েস্ট প্রসেস করুন এবং রেসপন্স স্ট্যাটাস ও বডি সহ কীটি সংরক্ষণ করুন।
4. যদি থাকে, পুনরায় প্রসেস না করে সংরক্ষিত রেসপন্স ফেরত দিন।

সীমাহীন স্টোরেজ বৃদ্ধি এড়াতে একটি যুক্তিসঙ্গত মেয়াদ (যেমন ২৪ ঘন্টা) সেট করুন।

২. Conditional Request ব্যবহার করুন

আপডেটের জন্য, হারানো আপডেট প্রতিরোধ করতে ETag এবং If-Match হেডার ব্যবহার করুন। সার্ভার বর্তমান স্টেটের প্রতিনিধিত্ব করে একটি ETag ফেরত দেয়। ক্লায়েন্ট এটি If-Match সহ ফেরত পাঠায়; যদি রিসোর্স পরিবর্তিত হয়, সার্ভার 412 Precondition Failed ফেরত দেয়। এটি PUT রিকোয়েস্টকে রেস কন্ডিশনের বিরুদ্ধে নিরাপদ করে তোলে।

PUT /articles/123
If-Match: "abc123"
Content-Type: application/json

{"title": "Updated title"}

৩. স্বাভাবিক Idempotency-এর জন্য PUT ডিজাইন করুন

যখন ক্লায়েন্ট রিসোর্স URL নির্ধারণ করতে পারে তখন POST-এর চেয়ে PUT পছন্দ করুন। উদাহরণস্বরূপ, PUT /users/{userId} স্বাভাবিকভাবেই idempotent কারণ পুনরাবৃত্ত কল একই রিসোর্স ওভাররাইট করে। শুধুমাত্র তখনই POST ব্যবহার করুন যখন সার্ভার ID নির্ধারণ করে।

৪. Unique Constraint দিয়ে ডুপ্লিকেট ডিটেকশন হ্যান্ডেল করুন

ব্যবসায়িক কী (যেমন অর্ডার নম্বর) এর উপর ডেটাবেস unique constraint-এর সাথে idempotency key একত্রিত করুন। যদি একটি ডুপ্লিকেট স্লিপ করে, ডেটাবেস এটি প্রত্যাখ্যান করে, এবং আপনি একটি স্পষ্ট বার্তা সহ 409 Conflict ফেরত দিতে পারেন।

REST API-এর জন্য Versioning স্ট্র্যাটেজি

API বিবর্তিত হয়। নতুন ফিল্ড, পরিবর্তিত আচরণ, বা সরানো এন্ডপয়েন্ট বিদ্যমান ক্লায়েন্টদের ভাঙতে পারে। Versioning আপনাকে তাদের ব্যাঘাত না করে পরিবর্তন প্রবর্তন করতে দেয়। এখানে বেশ কয়েকটি সাধারণ কৌশল রয়েছে:

বেশিরভাগ টিমের জন্য, URI path versioning সবচেয়ে বাস্তবসম্মত পছন্দ। এটি দৃশ্যমান, ডকুমেন্ট করা সহজ, এবং API গেটওয়ে ও CDN-এর সাথে ভালো কাজ করে।

ক্লায়েন্ট ভাঙার ছাড়াই কিভাবে Version করবেন

1. প্রথম দিন থেকেই পাথে v1 দিয়ে শুরু করুন। পরে versioning যোগ করা কঠিন।
2. একটি সংস্করণের মধ্যে কেবল সংযোজনমূলক পরিবর্তন: নতুন ঐচ্ছিক ফিল্ড, নতুন এন্ডপয়েন্ট। কখনো ফিল্ড সরাবেন বা নাম পরিবর্তন করবেন না।
3. সুন্দরভাবে ডেপ্রিকেট করুন: এন্ড-অফ-লাইফ ঘোষণা করুন, মাইগ্রেশন গাইড প্রদান করুন, এবং পুরনো সংস্করণের ব্যবহার মনিটর করুন।
4. Sunset হেডার ব্যবহার করুন: ক্লায়েন্টদের জানাতে Sunset: Sat, 31 Dec 2025 23:59:59 GMT।
5. সর্বোচ্চ দুটি সক্রিয় সংস্করণ বজায় রাখুন রক্ষণাবেক্ষণের বোঝা সীমিত করতে।

একসাথে প্রয়োগ: একটি ব্যবহারিক উদাহরণ

একটি পেমেন্ট API বিবেচনা করুন। আপনি idempotently একটি পেমেন্ট তৈরি করতে চান এবং এন্ডপয়েন্ট version করতে চান।

POST /v1/payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "amount": 1000,
  "currency": "USD"
}

সার্ভার লজিক:

• Redis-এ Idempotency-Key আছে কিনা চেক করুন।
• যদি থাকে, ক্যাশ করা রেসপন্স (স্ট্যাটাস + বডি) ফেরত দিন।
• যদি না থাকে, পেমেন্ট প্রসেস করুন, রেসপন্স সহ কী সংরক্ষণ করুন, 201 Created ফেরত দিন।

আপডেটের জন্য, ETag সহ PUT ব্যবহার করুন:

PUT /v1/payments/123
If-Match: "xyz789"
Content-Type: application/json

{"amount": 1500}

যদি ETag মেলে না, 412 ফেরত দিন। এটি সমকালীন পরিবর্তন ওভাররাইটিং প্রতিরোধ করে।

সাধারণ ভুল এবং সেগুলো এড়ানোর উপায়

• Idempotency key চিরকাল সংরক্ষণ করা: স্টোরেজ ব্লোট এড়াতে একটি TTL (যেমন 24h) সেট করুন।
• রেস কন্ডিশন উপেক্ষা করা: কী চেক ও সেট করতে পারমাণবিক অপারেশন (যেমন Redis SETNX) ব্যবহার করুন।
• অনেক দেরিতে versioning: শুরু থেকেই /v1 যোগ করুন।
• মাইনর সংস্করণে ব্রেকিং পরিবর্তন: রেসপন্স স্ট্রাকচার পরিবর্তন করে এমন যেকোনো পরিবর্তনকে মেজর হিসেবে বিবেচনা করুন।
• Idempotency ডকুমেন্ট না করা: স্পষ্টভাবে উল্লেখ করুন কোন এন্ডপয়েন্টগুলো Idempotency-Key সমর্থন করে।

FAQ

একটি idempotent REST API কী?

একটি idempotent REST API নিশ্চিত করে যে একই রিকোয়েস্ট একাধিকবার করলে একবার করার মতোই একই ফলাফল দেয়। এটি রিট্রাই নিরাপদে হ্যান্ডেল করার জন্য অত্যন্ত গুরুত্বপূর্ণ, বিশেষ করে POST-এর মতো non-idempotent মেথডের জন্য।

কোন HTTP মেথডগুলো idempotent?

GET, HEAD, PUT, DELETE, OPTIONS, এবং TRACE idempotent। POST এবং PATCH ডিফল্টভাবে idempotent নয়, তবে আপনি idempotency key-এর মতো কৌশল ব্যবহার করে সেগুলোকে idempotent করতে পারেন।

REST API version করার সবচেয়ে ভালো উপায় কী?

URI path versioning (যেমন /v1/users) সবচেয়ে সাধারণ এবং ব্যবহারিক পদ্ধতি। এটি স্পষ্ট, রাউট করা সহজ, এবং ক্যাশিং ও API গেটওয়ের সাথে ভালো কাজ করে। অন্যান্য বিকল্পের মধ্যে রয়েছে query parameter, custom header, এবং media type, কিন্তু এগুলোর ট্রেড-অফ আছে।

আপনার API-এর JSON রেসপন্স পরীক্ষা করতে প্রস্তুত? পেলোড দ্রুত ভ্যালিডেট এবং প্রিটি-প্রিন্ট করতে আমাদের JSON Formatter ব্যবহার করুন।