REST API নকশা — resource, status code, pagination, versioning আর idempotency

১ · REST কী — resource, representation আর Fielding-এর নীতি

পর্ব ০৬-এ নকশার ধাপ ৩-এ API-কে বলেছিলাম রেস্তোরাঁর মেনু, আর লিখেছিলাম দুই-চারটি মূল endpoint. এই পর্বে মেনুটি ভালোভাবে লেখার নিয়ম: কোন জিনিসের কী নাম, কোন কাজে কোন method, ভুল হলে কোন status code, বড় তালিকা কীভাবে ভাগ হবে, আর বদলানোর সময় পুরোনো app যেন না ভাঙে। HTTP বার্তার খুঁটিনাটি আছে Computer Networks কোর্সের HTTP পর্বে, আর DNS, TCP ও TLS পর্ব ০৭-এ; এখানে শুধু নকশার সিদ্ধান্ত।

পুরো পর্বে একটি উদাহরণ সাথে থাকবে: একটি আন্তঃজেলা বাস-টিকিট বুকিং সেবা (কাল্পনিক)। যাত্রী app-এ ট্রিপ খোঁজেন, কয়েক মিনিটের জন্য সিট ধরে রাখেন, মোবাইল ওয়ালেটে টাকা দেন; কাউন্টারের কর্মীও একই বুকিং বদলাতে পারেন। ঈদের আগের ভিড়, দুর্বল নেটওয়ার্কে বারবার retry, হালনাগাদ না করা পুরোনো app — API নকশার প্রায় সব কঠিন প্রশ্ন এখানে। টাকার খাতা আর ভিড়ে সিট বিক্রির পুরো নকশা পর্ব ৬০-এর case study-তে; এখানে শুধু API-র স্তর।

REST-এর তিনটি মূল শব্দ। Resource হলো যেকোনো জিনিস যার নাম দেওয়া যায় — একটি ট্রিপ, একটি বুকিং, বা একজন যাত্রীর সব বুকিংয়ের তালিকা। তার ঠিকানা URI, যেমন /v1/bookings/bk_1001. আর তারে যা যায় তা resource নিজে নয়, তার একটি representation — সাধারণত JSON-এ লেখা সেই মুহূর্তের একটি ছবি। একই বুকিংয়ের JSON রূপ app-এর জন্য, PDF রূপ টিকিট ছাপার জন্য — resource এক, রূপ দুটি।

Uniform interface-এর ভেতরে সবচেয়ে কড়া শর্তটির নাম HATEOAS: উত্তরের ভেতরেই থাকবে পরের কাজের link — যেমন সিট ধরে রাখার উত্তরে “পরিশোধ করুন” আর “বাতিল করুন”-এর ঠিকানা। ওয়েবসাইট ঠিক এভাবে চলে: আপনি কোনো URL মুখস্থ রাখেন না, link আর form ধরে এগোন। Fielding ২০০৮ সালের একটি ব্লগ লেখায় স্পষ্ট বলেন, hypertext ছাড়া কোনো API-কে REST বলা উচিত নয়।

বাস্তবে বেশিরভাগ “REST API” এই শর্ত মানে না: URL-এর ছক ডকুমেন্টেশনে থাকে, app সেটি কোডে বেঁধে রাখে। এগুলো আসলে REST-ধাঁচের HTTP-JSON API — তবু resource, method আর status code-এর সুবিধা পুরোপুরিই পাওয়া যায়। Leonard Richardson-এর একটি মাপকাঠি, যা Martin Fowler-এর ২০১০ সালের একটি লেখায় জনপ্রিয় হয় — Richardson maturity model — চার স্তরে ভাগ করে: ০, এক URL-এ সব কাজ POST দিয়ে; ১, আলাদা resource; ২, ঠিক HTTP method আর status code; ৩, hypermedia link. এই পর্বের নকশা স্তর ২-এ; link শুধু Location আর পরের পাতার cursor-এ।

২ · Method-এর অর্থ — safe, idempotent আর নিরাপদ retry

HTTP method একটি প্রতিশ্রুতি: ব্রাউজার, proxy, CDN আর retry-র লাইব্রেরি method দেখেই ঠিক করে উত্তর জমা রাখা বা আবার পাঠানো যাবে কি না। দুটি গুণ মনে রাখুন। Safe মানে client শুধু পড়তে চায়, server-এর অবস্থা বদলাতে চায় না। Idempotent মানে একবার পাঠানো আর দশবার পাঠানোর চূড়ান্ত প্রভাব এক।

OPTIONS আর method-এর protocol-স্তরের খুঁটিনাটি আছে HTTP পর্বের অংশ ৩-এ। নকশার চোখে তিনটি শিক্ষা:

• Idempotent মানে একই উত্তর নয়, একই অবস্থা। একটি বুকিং DELETE করলে প্রথমবার 204, দ্বিতীয়বার হয়তো 404 — কিন্তু দুবারের পরেও server-এর অবস্থা এক: বুকিংটি নেই।
• GET দিয়ে কখনো কিছু বদলাবেন না। GET /cancelBooking?id=1001 বিপজ্জনক: ব্রাউজারের prefetch বা ইমেইলের link-যাচাইকারী নিজে থেকেই GET পাঠাতে পারে, CDN উত্তর জমিয়ে রাখতে পারে।
• তৈরি করতে POST, না PUT? Server id ঠিক করলে POST /v1/bookings, উত্তরে 201 Created আর Location. Client নিজে অনন্য id বানালে PUT /v1/drafts/{draft_id} — idempotent, তাই retry-তে দ্বিতীয় খসড়া হয় না।

PATCH-এর body-র রূপও চুক্তির অংশ। সবচেয়ে সরল প্রমিত রূপ JSON Merge Patch (RFC 7396): শুধু বদলানো ঘর পাঠান, যেমন {"boarding": "Kallyanpur"}; কোনো ঘরে null পাঠালে সেটি মুছে যায়। আর CRUD-এর সাথে method-এর মিল — POST তৈরি, GET পড়া, PUT বা PATCH বদল, DELETE মোছা — একটি শুরু মাত্র; সব কাজ CRUD-এ পড়ে না, পরের অংশেই তা দেখব।

৩ · Resource আর URI-র নাম — বিশেষ্য, বহুবচন আর nesting-এর সীমা

ভালো URI পড়লেই বোঝা যায় কী পাওয়া যাবে, আর একটি endpoint দেখে বাকিগুলো আন্দাজ করা যায়। নিচের নিয়মগুলো আইন নয়, প্রচলিত রীতি; আসল নিয়ম একটাই — পুরো API-তে একই রীতি মানা।

CRUD-এ না পড়া কাজ — ধরে রাখা, বাতিল আর ফেরত

বুকিং বাতিল কি DELETE? মুছে ফেললে ইতিহাস আর ফেরতের হিসাব যায়। দুটি প্রচলিত পথ: কাজটিকেই resource বানানো — POST /v1/bookings/{id}/cancellation একটি বাতিল-রেকর্ড তৈরি করে; অথবা “custom method” — POST /v1/bookings/{id}:cancel, যেমনটি Google-এর প্রকাশিত API নির্দেশিকায় (AIP) দেখা যায়। একটি বেছে পুরো API-তে মানুন। সিট ধরে রাখা মডেল হয় বুকিং নিজেই হিসেবে: "status": "held" আর মেয়াদ expires_at; মেয়াদ পেরোলে server সিট ছেড়ে দেয়।

এবার পুরো সেবার endpoint ধাপে ধাপে — প্রতি ধাপে একটি প্রশ্ন, একটি সিদ্ধান্ত:

ছয় ধাপের ফল — পুরো সেবার চুক্তি এক নজরে। এই টেবিলের কোডগুলো কেন, তা পরের অংশে:

সব endpoint-এর জন্য সাধারণ: টোকেন নেই বা ভুল হলে 401, অনুমতি না থাকলে 403, সীমার বেশি অনুরোধে 429, আর server-এর দিকের ব্যর্থতায় ৫xx.

৪ · Status code বাছাই আর এক ছাঁচের ত্রুটি-বার্তা

Status code আসলে যন্ত্রের জন্য লেখা — app-এর retry-কোড, gateway, CDN আর monitoring সংখ্যাটি দেখেই সিদ্ধান্ত নেয়; মানুষের জন্য বিস্তারিত থাকে body-তে। তাই সব উত্তরে 200 দিয়ে body-তে “error” লেখা চলে না; এই খারাপ অভ্যাস আর সব কোডের পূর্ণ তালিকা আছে HTTP পর্বের অংশ ৪-এ। নকশাকারীর কাজ প্রতিটি পরিস্থিতির জন্য কোড বেছে চুক্তিতে লেখা। বাস-টিকিট সেবায়:

তিনটি চিরকালের তর্ক। 401 না 403? 401 মানে “আপনি কে, জানি না”; নামটি “Unauthorized” হলেও অর্থ authentication. 403 মানে “জানি আপনি কে, কিন্তু অনুমতি নেই।” 404 দিয়ে লুকানো: অন্য যাত্রীর বুকিং id-তে 403 দিলে জানিয়ে দেওয়া হয় যে বুকিংটি আছে; তাই অনেক API তখন 404 দেয়। 400 না 422? গঠনই ভুল হলে 400; গঠন ঠিক কিন্তু অর্থে ভুল হলে 422 — RFC 9110 (২০২২) একে মূল HTTP-তে এনেছে “Unprocessable Content” নামে। অনেক দল সব validation-এ 400 দেয়; চলবে, যদি নিয়মটি লেখা থাকে আর সব জায়গায় একই হয়।

একটি অনুরোধে একাধিক সমস্যা থাকলে কোনটি আগে — টোকেন নেই, JSON-ও ভাঙা? যাচাইয়ের ক্রম ঠিক না থাকলে একই অনুরোধে একেক সার্ভার একেক কোড দেয়। নিচের simulator একটি নির্দিষ্ট ক্রমে যাচাই চালায়; চালানোর আগে প্রতিটি লাইনের কোড আন্দাজ করুন:

// Which status code? The checks run in a FIXED order: the order is part of the API design.
function choose(r) {
  if (r.overQuota)               return ["429", "Retry-After: 30"];
  if (!r.token)                  return ["401", "WWW-Authenticate: Bearer"];
  if (r.badJson)                 return ["400", "body is not valid JSON"];
  if (!r.found || !r.canSee)     return ["404", r.found ? "hide that it exists" : "no such booking"];
  if (!r.allowed)                return ["403", "can see it, may not change it"];
  if (r.invalid)                 return ["422", "well-formed but breaks a rule"];
  if (r.staleEtag)               return ["412", "If-Match failed: re-read first"];
  if (r.conflict)                return ["409", "clashes with current state"];
  if (r.upstream === "busy")     return ["503", "Retry-After: 60"];
  if (r.upstream === "slow")     return ["504", "gateway gave up waiting"];
  if (r.upstream === "garbage")  return ["502", "bad reply from upstream"];
  if (r.async)                   return ["202", "Location: /v1/refunds/rf_51"];
  if (r.created)                 return ["201", "Location: /v1/bookings/bk_1002"];
  if (r.noBody)                  return ["204", "done, nothing to return"];
  return ["200", "here is the body"];
}
const ok = { token: true, found: true, canSee: true, allowed: true };
const cases = [
  ["book seat B4 (new booking)",       { ...ok, created: true }],
  ["read my booking",                  { ...ok }],
  ["seat B4 already sold",             { ...ok, conflict: true }],
  ["travel date in the past",          { ...ok, invalid: true }],
  ["JSON missing a closing brace",     { ...ok, badJson: true }],
  ["no Authorization header",          { ...ok, token: false }],
  ["someone else's booking id",        { ...ok, canSee: false }],
  ["agent tries to edit fare table",   { ...ok, allowed: false }],
  ["edit with an old ETag",            { ...ok, staleEtag: true }],
  ["refund needs bank, ~2 days",       { ...ok, async: true }],
  ["payment gateway timed out",        { ...ok, upstream: "slow" }],
  ["booking DB overloaded",            { ...ok, upstream: "busy" }],
  ["350 requests in one minute",       { ...ok, overQuota: true }],
];
for (const [what, req] of cases) console.log(what.padEnd(32) + choose(req).join("  "));

book seat B4 (new booking)      201  Location: /v1/bookings/bk_1002
read my booking                 200  here is the body
seat B4 already sold            409  clashes with current state
travel date in the past         422  well-formed but breaks a rule
JSON missing a closing brace    400  body is not valid JSON
no Authorization header         401  WWW-Authenticate: Bearer
someone else's booking id       404  hide that it exists
agent tries to edit fare table  403  can see it, may not change it
edit with an old ETag           412  If-Match failed: re-read first
refund needs bank, ~2 days      202  Location: /v1/refunds/rf_51
payment gateway timed out       504  gateway gave up waiting
booking DB overloaded           503  Retry-After: 60
350 requests in one minute      429  Retry-After: 30

এক ছাঁচের ত্রুটি — RFC 9457 problem details

প্রতিটি endpoint নিজের মতো ত্রুটি লিখলে app-কে প্রতিটির জন্য আলাদা কোড লিখতে হয়। IETF-এর Problem Details মানদণ্ড একটি সাধারণ ছাঁচ দেয়, media type application/problem+json. লেখার সময়ে সর্বশেষ সংস্করণ RFC 9457 (২০২৩), যা আগের RFC 7807 (২০১৬)-কে প্রতিস্থাপন করেছে। পাঁচটি মানক ঘর — type (সমস্যার ধরনের একটি URI, যা ডকুমেন্টেশনে নিয়ে যায়), title, status, detail আর instance (এই নির্দিষ্ট ঘটনার পরিচয়) — আর দরকারে নিজের বাড়তি ঘর।

POST /v1/bookings HTTP/1.1
Content-Type: application/json

{ "trip_id": "DHK-RJH-1027", "seat": "B4" }

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/seat-taken",
  "title": "Seat already taken",
  "status": 409,
  "detail": "Seat B4 on trip DHK-RJH-1027 was booked by another passenger.",
  "available_seats": ["B5", "C2"],
  "trace_id": "req_7f3a"
}

App পড়বে স্থির type, আর মানুষকে দেখাবে নিজের ভাষার বার্তা; trace_id দিয়ে support দল log-এ অনুরোধটি খুঁজে পায় (পর্ব ৫০); বাড়তি ঘর available_seats দেখে app সঙ্গে সঙ্গে বিকল্প দেখায়। আর 500-এ কখনো stack trace বা SQL নয় — সেটি আক্রমণকারীর জন্য মানচিত্র।

৫ · তালিকা ভাগে ভাগে — offset বনাম cursor, filter, sort আর sparse field

ঈদের আগের সপ্তাহে একটি জনপ্রিয় রুটে কয়েক লাখ বুকিং হতে পারে (ধরা যাক)। সব একবারে পাঠালে উত্তর বিশাল আর ধীর, server-এর মেমরিও ফুরায়। তাই pagination: প্রতি উত্তরে একটি ছোট পাতা, সাথে পরের পাতার চাবি। ডিফল্ট আর সর্বোচ্চ মাপ চুক্তিতে লিখুন — ধরা যাক ২০ আর ১০০; কেউ limit=100000 চাইলেও ১০০-তেই থামুন।

Offset pagination-এ ডেটাবেস OFFSET 50000 পেতে আগের ৫০,০০০ সারি সত্যিই একটা একটা করে পেরিয়ে ফেলে দেয় — offset যত বড়, কাজ তত বেশি; শেষের দিকের পাতা সবচেয়ে ধীর। Keyset pagination আগের পাতার শেষ সারির key মনে রাখে — “id ৯৯৯৯৬-এর চেয়ে ছোট পরের ৫টি” — আর index-এর B-tree ধরে সোজা সেখানে নামে; প্রথম আর লাখতম পাতার খরচ প্রায় সমান। দ্বিতীয় সমস্যা আরও সূক্ষ্ম: offset গোনে অবস্থান, আর অবস্থান বদলায়। পাতা ১ পড়ার পর মাথায় নতুন বুকিং এলে সবাই এক ঘর নিচে নামে, পাতা ২-এর প্রথম সারিটি আগের পাতারই শেষ সারি। মাঝে একটি সারি মুছে গেলে উল্টো — একটি সারি ওপরে উঠে আগের পাতার এলাকায় চলে যায়, পাঠক সেটি কখনো দেখেন না।

নিচের লাইভ SQL এডিটরে ১ লাখ বুকিংয়ের একটি টেবিল (“নমুনা ডেটাবেস” খুলে দেখতে পারেন): প্রথমে দুই পদ্ধতির query plan, তারপর পাতা পড়ার মাঝে একটি নতুন বুকিং আর একটি বাতিল। এটি single-node SQLite ডেমো — query plan আর কোন সারি এলো তা দেখায়; সময় মাপে না, বহু যন্ত্রে ভাগ করা ডেটাবেসের আচরণও দেখায় না। EXPLAIN QUERY PLAN query না চালিয়েই পথটি বলে।

-- Newest first, 5 per page. Sample table: 100,000 bookings, ids 1..100000.
-- 1) How does each method reach a deep page?
EXPLAIN QUERY PLAN
SELECT id, seat FROM bookings ORDER BY id DESC LIMIT 5 OFFSET 50000;
EXPLAIN QUERY PLAN
SELECT id, seat FROM bookings WHERE id < 50001 ORDER BY id DESC LIMIT 5;

-- 2) A reader fetches page 1 ...
SELECT group_concat(id, ' ') AS page_1
FROM (SELECT id FROM bookings ORDER BY id DESC LIMIT 5);
-- ... then a NEW booking arrives at the top.
INSERT INTO bookings VALUES (100001, '2026-10-10 09:00:00', 'DHK-RJH', 'B4');
SELECT group_concat(id, ' ') AS offset_page_2
FROM (SELECT id FROM bookings ORDER BY id DESC LIMIT 5 OFFSET 5);
SELECT group_concat(id, ' ') AS keyset_page_2       -- cursor: last id seen = 99996
FROM (SELECT id FROM bookings WHERE id < 99996 ORDER BY id DESC LIMIT 5);

-- 3) ... then booking 99993 is cancelled and deleted.
DELETE FROM bookings WHERE id = 99993;
SELECT group_concat(id, ' ') AS offset_page_3
FROM (SELECT id FROM bookings ORDER BY id DESC LIMIT 5 OFFSET 10);
SELECT group_concat(id, ' ') AS keyset_page_3       -- cursor: last id seen = 99991
FROM (SELECT id FROM bookings WHERE id < 99991 ORDER BY id DESC LIMIT 5);

page_1          100000 99999 99998 99997 99996
✓ INSERT — ১টি সারি বদলেছে
offset_page_2   99996 99995 99994 99993 99992
keyset_page_2   99995 99994 99993 99992 99991
✓ DELETE — ১টি সারি বদলেছে
offset_page_3   99990 99989 99988 99987 99986
keyset_page_3   99990 99989 99988 99987 99986

একই ঘটনা ছোট সংখ্যায়, পাতা ধরে ধরে — দুজন পাঠক, একজন offset-এ, আরেকজন cursor-এ:

Cursor-এর নকশা — অস্বচ্ছ, অনন্য, indexed

• অস্বচ্ছ টোকেন: cursor-এর ভেতরে শেষ key আর চলতি filter-sort লিখে base64 করুন, দরকারে signature দিন। Client শুধু ফেরত পাঠাবে — তাহলে ভেতরের ছক পরে বদলানো যায়।
• Sort key অনন্য হতে হবে: শুধু departure_at ধরে sort করলে একই সময়ের দুটি ট্রিপের একটি পাতার সীমানায় হারাতে পারে। শেষে id জুড়ে দিন — ORDER BY departure_at, id, শর্ত (departure_at, id) > (:t, :id), আর সেই ক্রমের একটি composite index (পর্ব ২১)।
• উত্তরের রূপ: {"items": […], "next_cursor": "…", "has_more": true}, অথবা Link header-এ rel="next" (RFC 8288).
• মোট সংখ্যা দামি: প্রতি পাতায় COUNT(*) মানে প্রতিবার পুরো তালিকা গোনা; দরকারে আনুমানিক সংখ্যা দিন।
• Offset কখন ঠিক: ছোট, প্রায় স্থির তালিকায়, গভীরতার একটি সীমা টেনে।

Filter, sort আর sparse field

তালিকার ওপর শর্ত দেয় query parameter:

GET /v1/bookings?trip_id=DHK-RJH-1027&status=confirmed
    &sort=-created_at&fields=id,seat,status&limit=20

sort=-created_at-এর বিয়োগ চিহ্ন মানে উল্টো ক্রম — একটি প্রচলিত রীতি। fields দিয়ে sparse fieldset: শুধু তিনটি ঘর — মোবাইল ডেটায় বড় সাশ্রয়। দুটি সাবধানতা। কোন ঘরে filter আর sort চলবে, তার নির্দিষ্ট তালিকা রাখুন, কারণ প্রতিটির পেছনে একটি index লাগে। আর অচেনা parameter এলে চুপচাপ উপেক্ষা না করে 400 দিন — নইলে একটি বানান ভুল (staus=) নিঃশব্দে পুরো তালিকা ফিরিয়ে দেবে। ঘর বাছাইয়ের ধারণা আরও এগিয়ে নিয়েছে GraphQL (পর্ব ০৯)।

৬ · Versioning আর সামঞ্জস্য — পুরোনো app না ভেঙে বদলানো

অনেকে মাসের পর মাস app হালনাগাদ করেন না। তাই API একটি চুক্তি: আজকের কোনো ঘর কাল হঠাৎ সরালে লাখো ফোনে app ভেঙে যাবে। Backward compatibility রাখার মূল নিয়ম: যোগ করুন, ভাঙবেন না।

যে পরিবর্তন পুরোনো client ভাঙতে পারে, তা breaking change; তখন লাগে নতুন সংস্করণ — API versioning. সংস্করণ কোথায় লিখবেন, তার তিনটি প্রচলিত পথ:

বড় সংস্করণ বিরল রাখুন — প্রতিটি মানে দুটি কোড-পথ বছরের পর বছর চালানো। Schema evolution-এর নিয়ম আসবে পর্ব ১২-এ।

অবসরের পরিকল্পনা — Deprecation আর Sunset

পুরোনো সংস্করণ বন্ধের আগে যন্ত্রকেও জানাতে পুরোনো endpoint-এর উত্তরে দুটি header যোগ করুন — Deprecation আর Sunset:

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1796083200
Sunset: Wed, 30 Jun 2027 23:59:59 GMT
Link: <https://developer.example.com/migrate-to-v2>; rel="deprecation"

Deprecation (RFC 9745, ২০২৫) জানায় endpoint-টি কবে থেকে পুরোনো — এখানে Unix সময় 1796083200, অর্থাৎ ১ ডিসেম্বর ২০২৬; Sunset (RFC 8594, ২০১৯) জানায় কোন মুহূর্তের পর এটি আর না-ও চলতে পারে। নম্বর আর খুঁটিনাটি লেখার সময়ের; ব্যবহারের আগে মূল RFC মিলিয়ে নিন। সাথে client id ধরে পুরোনো সংস্করণের ব্যবহার মাপুন, শেষের দিকের ব্যবহারকারীদের সরাসরি জানান, আর Sunset-এর পর উত্তর দিন 410 Gone. কিছু প্রতিষ্ঠান বন্ধের আগে ছোট পরিকল্পিত বিরতি (brownout) দেয়, যাতে ভুলে যাওয়া client-রা আগেভাগে টের পায়।

৭ · নিরাপদ retry — POST-এ idempotency key

App টাকা দেওয়ার অনুরোধ পাঠাল, ৫ সেকেন্ডে উত্তর এলো না — timeout. টাকা কি কেটেছে? অনুরোধ পথেই হারাতে পারে, কাজ শেষের পর উত্তরটি হারাতে পারে, বা server এখনো কাজ করছে — client-এর দিক থেকে তিনটিই এক রকম। আবার না পাঠালে হয়তো টিকিট হয়নি; পাঠালে হয়তো দুবার টাকা কাটবে। POST idempotent নয়, তাই লাগে একটি idempotency key.

নিয়মটি কীভাবে চলে

1. Client key বানায় — প্রতিটি অভিপ্রায়ে একবার। যাত্রী “পরিশোধ” চাপলেন — একটি অভিপ্রায়। App একটি UUID বানিয়ে Idempotency-Key header-এ পাঠায়, সব retry-তে একই key, আর চূড়ান্ত উত্তর না আসা পর্যন্ত key-টি ফোনে রাখে। প্রতি retry-তে নতুন key মানে পুরো ব্যবস্থাটাই অর্থহীন।
2. Server key খোঁজে, না পেলে দাবি করে। (client, key) জোড়া UNIQUE constraint-সহ একটি টেবিলে, সাথে body-র hash — request fingerprint — আর অবস্থা “চলছে”। দুটি retry একসাথে এলেও ডেটাবেস একটিকেই ঢুকতে দেয়।
3. কাজ, তারপর উত্তর জমা। টাকা কাটার পর status আর body key-এর পাশে জমা, অবস্থা “শেষ”।
4. Retry এলে: কাজ শেষ আর hash মেলে — জমা উত্তর হুবহু; কাজ চলছে — 409; hash মেলে না — 422; বাধ্যতামূলক key-ই নেই — 400.
5. মেয়াদ: সাধারণত কয়েক ঘণ্টা থেকে কয়েক দিন, API ভেদে আলাদা; তার পরে একই key নতুন অনুরোধ ধরা হতে পারে।

Header-টির নাম আর এই কোডগুলো এসেছে IETF-এর একটি খসড়া থেকে (The Idempotency-Key HTTP Header Field); লেখার সময়ে এটি চূড়ান্ত RFC হয়নি, যদিও বহু পেমেন্ট API-র প্রকাশিত ডকুমেন্টেশনে একই ধাঁচ দেখা যায়। পুরো পথটি ছবিতে:

দুটি জিনিস লক্ষ করুন। এক, key আর বুকিং একই transaction-এ লেখা, তাই “বুকিং হলো কিন্তু উত্তর জমা হলো না” এমন আধা অবস্থা হয় না (পর্ব ২৪)। দুই, বাইরের payment gateway আমাদের transaction-এর বাইরে; তাই তাকেও একই key, বা তা থেকে বানানো key পাঠাতে হয়, যাতে আমাদের retry-তেও gateway দ্বিতীয়বার টাকা না কাটে। শিকলের প্রতিটি কড়া idempotent না হলে শিকল দুর্বল — গভীর আলোচনা পর্ব ৩৪-এ (delivery semantics), টিকিট-পেমেন্টের পূর্ণ নকশা পর্ব ৬০-এ। ঘটনাক্রম ধাপে ধাপে:

এবার simulator-এ একই ঘটনা, সাথে কয়েকটি ভুল ব্যবহার। Key-এর store একটি Map, body-র fingerprint ৩২-বিটের FNV-1a hash, আর যাত্রীর ওয়ালেটে ৫,০০০ টাকা। ধাপ ১-এ প্রথম অনুরোধটি ধীর — কাজ চলতে চলতেই retry আসে:

// Idempotency-Key server simulator: one process, in-memory store, no randomness.
function fnv1a(s) {                                   // 32-bit FNV-1a hash of the request body
  let h = 0x811c9dc5;
  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
  return h.toString(16).padStart(8, "0");
}
const store = new Map();             // key -> { hash, reply }   (reply missing = still running)
let wallet = 5000, nextId = 77;      // passenger's wallet in Tk; next payment id

function handle(key, body, slow = false) {
  const hash = fnv1a(JSON.stringify(body)), rec = store.get(key);
  if (rec && rec.hash !== hash) return "422 key reused with a different body";
  if (rec && !rec.reply)        return "409 first attempt still running";
  if (rec)                      return rec.reply + "  (replayed)";
  store.set(key, { hash });                         // claim the key BEFORE the side effect
  return slow ? null : finish(key, body);
}
function finish(key, body) {                        // the side effect: charge exactly once
  wallet -= body.amount;
  const reply = "201 pay_" + nextId++ + " charged " + body.amount;
  store.get(key).reply = reply;
  return reply;
}
const pay = { booking: "bk_1001", amount: 850 };
const show = (step, r) => console.log(step.padEnd(30) + String(r ?? "(still working)").padEnd(38) + "wallet " + wallet);
console.log("body hash = " + fnv1a(JSON.stringify(pay)));
show("1 POST, key K1 (slow)",       handle("K1", pay, true));
show("2 retry K1 after timeout",    handle("K1", pay));
show("  server finishes K1",        finish("K1", pay) + "  (reply lost)");
show("3 retry K1 after backoff",    handle("K1", pay));
show("4 retry K1 again",            handle("K1", pay));
show("5 K1 but amount 900",         handle("K1", { ...pay, amount: 900 }));
show("6 new key K2, same body",     handle("K2", pay));
console.log("charges made: " + (nextId - 77) + "; without keys, steps 1-4 alone = 4 charges");

body hash = 459ba005
1 POST, key K1 (slow)         (still working)                       wallet 5000
2 retry K1 after timeout      409 first attempt still running       wallet 5000
  server finishes K1          201 pay_77 charged 850  (reply lost)  wallet 4150
3 retry K1 after backoff      201 pay_77 charged 850  (replayed)    wallet 4150
4 retry K1 again              201 pay_77 charged 850  (replayed)    wallet 4150
5 K1 but amount 900           422 key reused with a different body  wallet 4150
6 new key K2, same body       201 pay_78 charged 850                wallet 3300
charges made: 2; without keys, steps 1-4 alone = 4 charges

৮ · একসাথে সম্পাদনা আর caching — ETag, If-Match আর 304

এবার অন্য সমস্যা: একই বুকিং দুজন একসাথে বদলাচ্ছেন। কাউন্টারের কর্মী সিট B4 থেকে C2 করলেন; প্রায় একই সময়ে যাত্রী app-এ ওঠার জায়গা গাবতলী থেকে কল্যাণপুর করলেন। দুজনই পুরোনো কপি পড়ে পুরো বুকিং PUT করলে পরের জন আগের জনের বদল মুছে দেন — lost update. কেউ ত্রুটি দেখেন না; যাত্রী বাসে উঠে দেখেন সিট আবার B4.

সমাধান optimistic concurrency: লক না ধরে সবাইকে পড়তে দিন, লেখার মুহূর্তে যাচাই করুন। HTTP-তে এর হাতিয়ার ETag — resource-এর সংস্করণের ছাপ। GET-এর উত্তরে server ETag দেয়; লেখার সময় client সেটি If-Match-এ ফেরত পাঠায় — একটি conditional request. না মিললে, অর্থাৎ মাঝে কেউ বদলেছে, উত্তর 412 Precondition Failed; client নতুন করে পড়ে, মিলিয়ে, আবার চেষ্টা করে। If-Match ছাড়া লেখা বন্ধ রাখতে চাইলে 428 Precondition Required (RFC 6585). W/ দিয়ে শুরু “weak” ETag If-Match-এ চলে না, কারণ লেখার শর্তে কড়া তুলনা লাগে।

// Optimistic concurrency with ETag + If-Match: two clients edit the same booking.
function fnv1a(s) {
  let h = 0x811c9dc5;
  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
  return h.toString(16).padStart(8, "0");
}
const db = { bk_1001: { seat: "B4", boarding: "Gabtoli" } };
const etag = (id) => '"' + fnv1a(JSON.stringify(db[id])) + '"';

function GET(id, ifNoneMatch) {
  if (ifNoneMatch === etag(id)) return { status: 304, etag: etag(id) };   // your copy is current
  return { status: 200, etag: etag(id), body: { ...db[id] } };
}
function PUT(id, body, ifMatch, checkPrecondition = true) {
  if (checkPrecondition && !ifMatch) return { status: 428 };               // If-Match required
  if (checkPrecondition && ifMatch !== etag(id)) return { status: 412, etag: etag(id) };
  db[id] = body;                                                           // full replacement
  return { status: 200, etag: etag(id) };
}
const log = (who, r) => console.log(who.padEnd(34) + r.status + "  " + (r.etag || "") +
  "  db=" + JSON.stringify(db.bk_1001));
const a = GET("bk_1001"); log("A (counter) GET", a);
const b = GET("bk_1001"); log("B (app) GET", b);
log("A PUT seat C2, If-Match old", PUT("bk_1001", { ...a.body, seat: "C2" }, a.etag));
log("B PUT boarding, If-Match old", PUT("bk_1001", { ...b.body, boarding: "Kallyanpur" }, b.etag));
log("B PUT with no If-Match", PUT("bk_1001", { ...b.body, boarding: "Kallyanpur" }));
const b2 = GET("bk_1001"); log("B re-reads (GET)", b2);
log("B PUT boarding, If-Match new", PUT("bk_1001", { ...b2.body, boarding: "Kallyanpur" }, b2.etag));
log("A GET If-None-Match old", GET("bk_1001", a.etag));
const c = GET("bk_1001"); log("A GET If-None-Match current", GET("bk_1001", c.etag));
db.bk_1001 = { seat: "B4", boarding: "Gabtoli" };                          // replay without checks
PUT("bk_1001", { ...a.body, seat: "C2" }, null, false);
log("no-check server, B then writes", PUT("bk_1001", { ...b.body, boarding: "Kallyanpur" }, null, false));

A (counter) GET                   200  "f52f8296"  db={"seat":"B4","boarding":"Gabtoli"}
B (app) GET                       200  "f52f8296"  db={"seat":"B4","boarding":"Gabtoli"}
A PUT seat C2, If-Match old       200  "4037343f"  db={"seat":"C2","boarding":"Gabtoli"}
B PUT boarding, If-Match old      412  "4037343f"  db={"seat":"C2","boarding":"Gabtoli"}
B PUT with no If-Match            428    db={"seat":"C2","boarding":"Gabtoli"}
B re-reads (GET)                  200  "4037343f"  db={"seat":"C2","boarding":"Gabtoli"}
B PUT boarding, If-Match new      200  "436016c8"  db={"seat":"C2","boarding":"Kallyanpur"}
A GET If-None-Match old           200  "436016c8"  db={"seat":"C2","boarding":"Kallyanpur"}
A GET If-None-Match current       304  "436016c8"  db={"seat":"C2","boarding":"Kallyanpur"}
no-check server, B then writes    200  "333cb88f"  db={"seat":"B4","boarding":"Kallyanpur"}

Server-এর ভেতরে If-Match সাধারণত চলে একটি version কলাম দিয়ে, আর যাচাই ও লেখা হয় একটিই UPDATE-এ — আলাদা SELECT আর UPDATE করলে দুইয়ের মাঝখানে আবার কেউ ঢুকে পড়তে পারে। এই compare-and-set নিচের লাইভ SQL-এ দেখুন:

-- Optimistic concurrency inside the server: the ETag maps to a version column.
CREATE TABLE bookings (id TEXT PRIMARY KEY, seat TEXT NOT NULL,
                       boarding TEXT NOT NULL, version INTEGER NOT NULL);
INSERT INTO bookings VALUES ('bk_1001', 'B4', 'Gabtoli', 1);

-- A (counter) and B (app) both read version 1. A writes first:
UPDATE bookings SET seat = 'C2', version = version + 1
WHERE id = 'bk_1001' AND version = 1;          -- 1 row changed: 200, new ETag "v2"
-- B still sends If-Match "v1":
UPDATE bookings SET boarding = 'Kallyanpur', version = version + 1
WHERE id = 'bk_1001' AND version = 1;          -- 0 rows changed: 412
SELECT id, seat, boarding, version FROM bookings;
-- B re-reads (version 2), merges its change, retries:
UPDATE bookings SET boarding = 'Kallyanpur', version = version + 1
WHERE id = 'bk_1001' AND version = 2;
SELECT id, seat, boarding, version FROM bookings;

API-র cache header — কোন উত্তর কতক্ষণ

পড়ার দিকে ETag দেয় If-None-Match আর body-ছাড়া 304 (simulator-এর “If-None-Match current” লাইন)। যাচাই ছাড়া কপি কতক্ষণ চলবে, তা বলে Cache-Control-এর max-age — একটি TTL. API-তে তিন ধরনের উত্তর:

নামের ফাঁদ: no-cache মানে “ব্যবহারের আগে যাচাই”, জমা না রাখার নির্দেশ no-store. পুরো নিয়ম Computer Networks-এর ওয়েব caching পর্বে; CDN পর্ব ১৭-এ আর caching কৌশল পর্ব ২৮-এ।

৯ · দীর্ঘ কাজ, batch, ডকুমেন্টেশন আর নিরাপত্তা

দীর্ঘ কাজ — 202, অবস্থা-resource আর webhook

বাতিলের পর টাকা ফেরতে কয়েক মিনিট থেকে কয়েক দিন লাগে; এতক্ষণ সংযোগ খোলা রাখা যায় না, gateway অনেক আগেই 504 দেবে। তাই long-running operation-এর ছক: সঙ্গে সঙ্গে 202 Accepted আর একটি অবস্থা-resource-এর ঠিকানা; ভারী কাজ চলে পেছনের worker-এ, প্রায়ই queue থেকে — asynchronous processing (পর্ব ৩১, ৩৭)।

POST /v1/bookings/bk_1001/cancellation HTTP/1.1
Authorization: Bearer <token>
Idempotency-Key: 3f9a2c1e-7b4d-4e8a-9c2f-5d6e7f8a9b0c

HTTP/1.1 202 Accepted
Location: /v1/refunds/rf_51
Retry-After: 30
Content-Type: application/json

{ "refund_id": "rf_51", "status": "pending", "amount": 850 }

GET /v1/refunds/rf_51 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{ "refund_id": "rf_51", "status": "succeeded", "completed_at": "2026-11-03T10:15:00Z" }

Client দুইভাবে ফল জানে। Polling: অবস্থা-resource-এ কিছুক্ষণ পরপর GET — সরল, কিন্তু অনেক বৃথা অনুরোধ; Retry-After বলে দেয় কতক্ষণ পরপর। Webhook: কাজ শেষ হলে server নিজেই client-এর নিবন্ধিত URL-এ POST পাঠায়। তার তিন নিয়ম: গোপন চাবিতে বানানো signature (যেমন HMAC), যাতে প্রাপক উৎস যাচাই করতে পারেন; না পৌঁছালে backoff-সহ আবার পাঠানো; আর প্রতিটি event-এর অনন্য id, কারণ একই event একাধিকবার পৌঁছাতে পারে — প্রাপককেও idempotent হতে হয়। সঙ্গে সঙ্গে খবর পৌঁছানোর অন্য পথ — long polling, SSE, WebSocket — পর্ব ১০-এ।

Batch endpoint — অনেক কাজ এক অনুরোধে

কাউন্টারের কর্মী একটি পরিবারের জন্য একসাথে ছয়টি সিট ধরতে চান। ছয়বার আসা-যাওয়ার বদলে একটি batch endpoint: POST /v1/bookings:batch. তিনটি সিদ্ধান্ত চুক্তিতে লিখুন। এক, সব-বা-কিছুই-না (atomic), না আংশিক সফলতা? পরিবারের সিটে সাধারণত সব-বা-কিছুই-না। দুই, আংশিক হলে প্রতিটি অংশের আলাদা status — অনেক API তখন 200 দিয়ে body-তে প্রতিটির ফল দেয়, কেউ কেউ WebDAV থেকে আসা 207 Multi-Status. তিন, সর্বোচ্চ কয়টি অংশ (ধরা যাক ৫০), আর পুরো batch-এর জন্য একটি idempotency key.

ডকুমেন্টেশন — OpenAPI দিয়ে চুক্তি লেখা

চুক্তি শুধু wiki-তে থাকলে কোড আর লেখা দ্রুত আলাদা হয়ে যায়। OpenAPI Specification চুক্তিটিকে যন্ত্র-পাঠযোগ্য YAML বা JSON-এ লেখে; একই ফাইল থেকে ডকুমেন্টেশনের পাতা, client-এর কোড (SDK), নকল server আর স্বয়ংক্রিয় contract test বানানো যায়। অনেক দল contract-first চলে: কোডের আগে OpenAPI ফাইল লিখে app আর backend দল মিলিয়ে নেয়। এর জন্ম Swagger নামে, ২০১০-এর দশকের শুরুতে; ২০১৫–১৬ সালে Linux Foundation-এর অধীন OpenAPI Initiative-এর হাতে গিয়ে নতুন নাম পায়। নিচে টাকা দেওয়ার endpoint-এর একটি অংশ, সংস্করণ 3.1-এর রূপে (খুঁটিনাটি সংস্করণভেদে আলাদা):

openapi: 3.1.0
info:
  title: Bus Booking API (fictional)
  version: 1.4.0
paths:
  /v1/bookings/{booking_id}/payments:
    post:
      summary: Pay for a held booking
      parameters:
        - name: booking_id
          in: path
          required: true
          schema: { type: string }
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string, maxLength: 64 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, method]
              properties:
                amount: { type: integer, minimum: 1, description: Amount in Taka }
                method: { type: string, enum: [wallet, card] }
      responses:
        "201":
          description: Payment created; the same reply is replayed for a repeated key
        "400":
          description: Idempotency-Key header missing
        "409":
          description: Same key still in progress, or the hold has expired
        "422":
          description: Key reused with a different body, or a business rule is broken
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/Problem" }

Idempotency-Key চুক্তিতেই বাধ্যতামূলক, আর 201-এর বর্ণনায় retry-র আচরণও লেখা। প্রতিটি পরিবর্তনে ফাইলটি আগের সংস্করণের সাথে স্বয়ংক্রিয়ভাবে তুলনা করলে breaking change merge-এর আগেই ধরা পড়ে।

নিরাপত্তার মূল নিয়ম — সংক্ষেপে

• শুধু HTTPS: সাধারণ HTTP-তে টোকেন আর ব্যক্তিগত তথ্য তারে খোলা; এমন অনুরোধ প্রত্যাখ্যান করুন (TLS পর্ব)।
• পরিচয় header-এ: Authorization: Bearer <token>; টোকেন কীভাবে আসে — OAuth 2.0 আর OpenID Connect — পর্ব ৫২-এ।
• গোপন কিছু URL-এ নয়: টোকেন, OTP বা পাসওয়ার্ড query string-এ গেলে server log, ব্রাউজারের history আর Referer header-এ থেকে যায়।
• প্রতিটি অনুরোধে বস্তুভিত্তিক অনুমতি: লগইন যাচাই যথেষ্ট নয়; GET /v1/bookings/bk_1001-এ দেখতে হবে বুকিংটি এই যাত্রীরই কি না — object-level authorization. OWASP-এর API Security Top 10-এ এর অভাব (Broken Object Level Authorization) সবার ওপরে, ২০১৯ আর ২০২৩ দুই সংস্করণেই।
• সীমা আর আকার: client-প্রতি rate limit, পেরোলে 429 আর Retry-After (পর্ব ৪৯); body-র সর্বোচ্চ আকার (বেশি হলে 413); pagination-এর সর্বোচ্চ limit.
• ত্রুটিতে কম কথা: 500-এ stack trace নয়; লগইনে “ভুল পাসওয়ার্ড” আর “এমন ব্যবহারকারী নেই” আলাদা করে বলবেন না।

এর অনেকটা এক জায়গায় প্রয়োগ করা যায় API gateway-তে (পর্ব ১১)।

১০ · AI-এর যুগে API নকশা — খসড়া AI-র, চুক্তি আপনার

AI-এর কাছে বাস-টিকিট বুকিংয়ের REST API চাইলে কয়েক সেকেন্ডে endpoint-এর তালিকা, এমনকি পুরো OpenAPI ফাইলও আসে। দেখতে গোছানো, কিন্তু কিছু চেনা ভুল বারবার দেখা যায়:

AI-এর API খসড়া গ্রহণের আগে — চেকলিস্ট

• প্রতিটি endpoint বিশেষ্য আর ঠিক method-এ; কোনো GET কিছু বদলায় না
• প্রতিটি ত্রুটির জন্য একটি status code আর এক ছাঁচের problem+json
• বড় তালিকায় cursor, অনন্য sort key, index আর সর্বোচ্চ limit
• টাকার POST-এ idempotency key-এর store, body hash, চলমান অবস্থা আর মেয়াদ যাচাই করেছি
• একসাথে সম্পাদনা আর timeout-এর ঘটনাক্রম হাতে চালিয়ে দেখেছি
• RFC নম্বর, header আর পণ্যের সীমা মূল উৎসে মিলিয়েছি; সম্ভব হলে ছোট simulation বা load test চালিয়েছি