REST resource নকশা — URL, method আর সম্পর্ক

১ · API একটি চুক্তি — কে ডাকে, কী প্রতিশ্রুতি

পর্ব ২৫-এ আপনি Express-এ route বানিয়েছেন, 201 আর 404 ফেরত দিয়েছেন। কোড চলেছে। কিন্তু একটি প্রশ্ন তখন ওঠেনি: ঠিকানাটি /api/orders হবে, নাকি /placeOrder? দুটিই চলে। মডিউল ৪ শিখিয়েছে কীভাবে বানাতে হয়। মডিউল ৫-এর প্রশ্ন হলো কী বানাবেন।

Server যে ঠিকানা, ডেটার আকার আর আচরণের কথা দেয়, তার পুরোটাই একটি API contract, বাংলায় চুক্তি। কাগজে লেখা না থাকলেও চুক্তি থাকে, কারণ client-এর কোড সেই আচরণের ওপরই দাঁড়িয়ে আছে।

চুক্তি কঠিন হয় কারণ client আপনার হাতে থাকে না। “বাজারঘর”-এর client কারা?

তাই ভালো API নকশার লক্ষ্য তিনটি। ব্যবহারকারী অনুমান করে ঠিকানা বলতে পারবেন, সব জায়গায় একই নিয়ম চলবে, আর ভুল ব্যবহার কঠিন হবে। সুন্দর URL নিজে লক্ষ্য নয়, লক্ষ্য হলো কম বিস্ময়।

উচ্চ স্তরের নকশা, যেমন retry, cache আর সিস্টেমজুড়ে সিদ্ধান্ত, আছে সিস্টেম ডিজাইন কোর্সের REST API নকশা পর্বে। সেগুলো আবার শেখানো হবে না। এখানে আমরা Express-এ চলা একটি আসল API গড়ব। Status code আর error format আসবে পর্ব ৩৩ (Status code আর error format)-এ, pagination পর্ব ৩৪-এ, versioning পর্ব ৩৫-এ।

২ · REST আসলে কী, আর সবাই যাকে REST বলে

REST কোনো library বা standard নয়। ২০০০ সালে Roy Fielding তাঁর PhD গবেষণাপত্রে web-এর স্থাপত্য ব্যাখ্যা করতে শব্দটি ব্যবহার করেন: Representational State Transfer. বিষয়টি হলো কয়েকটি শর্ত, যেগুলো মানলে web-এর মতো বিশাল সিস্টেম টিকে থাকে। সাধারণ ভাষায়:

Uniform interface-এর ভেতরে আছে আরেকটি শর্ত: উত্তরের ভেতরের link ধরেই client পরের কাজ খুঁজে পাবে। আজ মানুষ “REST API” বলতে সাধারণত এর চেয়ে অনেক কম বোঝেন: URL-এ resource, HTTP method, JSON. ২০০৮ সালের অক্টোবরে Fielding নিজেই ব্লগে লেখেন, যেকোনো HTTP interface-কে REST API বলায় তিনি বিরক্ত। “বাজারঘর” API-ও কঠোর অর্থে REST নয়, HTTP-ভিত্তিক resource API. এই পর্বের নামে “REST” শব্দটি প্রচলিত অর্থেই ব্যবহার করা হয়েছে, ভুল ধারণা হিসেবে নয়।

REST-ধাঁচ বনাম RPC-ধাঁচ

RPC (Remote Procedure Call) মানে দূরের ফাংশন ডাকা। এখানে কেন্দ্রে থাকে কাজ, জিনিস নয়। দুটিই বৈধ নকশা। পার্থক্য দেখুন:

একই টিমের TypeScript client আর server হলে RPC-ধাঁচ খুবই সুবিধাজনক। এটি পর্ব ৩৭ (Type-safe API)-এ দেখবেন। আর ক্লায়েন্ট নিজে field বেছে নিতে চাইলে GraphQL, পর্ব ৩৬-এ।

৩ · Resource আর action — URL-এর নাম

নকশা শুরু হয় একটি সহজ অনুশীলনে। ক্রেতার গল্প লিখে বিশেষ্যগুলো দাগ দিন: “ক্রেতা পণ্য দেখেন, কার্ট-এ রাখেন, অর্ডার করেন, পরে review লেখেন।” এই বিশেষ্যগুলোই resource. ক্রিয়াগুলো (দেখা, রাখা, করা) আলাদা করে URL-এ লিখতে হয় না, কারণ HTTP-তে ক্রিয়ার জায়গা আগে থেকেই আছে: method.

URL-এর path সাধারণভাবে case-sensitive ধরা হয়। Express ডিফল্টে উদার: আমাদের run-এ /API/Products আর /api/products/ দুটিই /api/products-এর route-এ মিলে 200 দিয়েছে। কিন্তু cache বা proxy এগুলোকে আলাদা ঠিকানা ধরতে পারে। তাই ছোট হাতের একটিই রূপ রাখুন। Hyphen-এর লিখনরীতিকে বলে kebab-case. একটি ব্যতিক্রম: ক্রেতার নিজের কার্ট একটিই, তাই /api/cart একবচন। একে বলে singleton resource. বহুবচনের নিয়ম collection-এর জন্য, একক জিনিসের জন্য নয়।

নিচে একটি খারাপ URL ধাপে ধাপে সারানো হলো। প্রতিটি ধাপে একটি করে ভুল কমছে।

GET /updateProductPrice?id=2&price=185.50

কোন জিনিস? product, id 2
GET /products/2?price=185.50 (updateProductPrice বাদ)

GET /api/products/2?price=185.50

PATCH /api/products/2?price=185.50

PATCH /api/products/2
Content-Type: application/merge-patch+json

{"pricePaisa":18550}

আগে: GET /updateProductPrice?id=2&price=185.50
পরে: PATCH /api/products/2  {"pricePaisa":18550}

এই নিয়মগুলো যন্ত্রকেও শেখানো যায়। নিচের ছোট lint একটি route তালিকা পরীক্ষা করে। বড় টিমে এমন নিয়ম CI-তে চলে, যাতে নকশার ভুল review-এর আগেই ধরা পড়ে।

// শেখার মডেল: একটি ছোট URL lint, নিয়মগুলো এই পর্বের নকশা থেকে নেওয়া
const VERBS = /^(get|create|add|update|delete|remove|fetch|list)([A-Z_-]|$)/;
const SINGULAR = /^(product|order|review|user)$/;

function lint(route) {
  const [method, path] = route.split(" ");
  const parts = path.replace(/^\/api\//, "").split("/");
  const names = parts.filter((p) => !p.startsWith(":"));
  const issues = [];
  if (names.some((n) => VERBS.test(n))) issues.push("verb in URL");
  if (names.some((n) => /[A-Z_]/.test(n))) issues.push("use lowercase-hyphen");
  if (SINGULAR.test(names[0])) issues.push("collection should be plural");
  if (names.length > 3) issues.push("nested too deep");
  if (method === "GET" && /\/(pay|cancel|logout)$/.test(path)) issues.push("GET must be safe");
  return issues;
}

const routes = [
  "POST /api/createOrder",
  "GET /api/product/:id",
  "GET /api/orders/:id/cancel",
  "POST /api/Order_Items",
  "GET /api/shops/:id/products/:id/reviews/:id/replies",
  "GET /api/products/:id/reviews",
  "PUT /api/cart/items/:productId",
  "POST /api/orders/:id/cancellation",
];
for (const r of routes) {
  const issues = lint(r);
  console.log(issues.length ? "BAD " : "OK  ", r, issues.join("; "));
}

৪ · Method-এর অর্থ — safe, idempotent, cacheable

Method শুধু লেবেল নয়। HTTP-এর standard RFC 9110 (২০২২) প্রতিটি method-এর কিছু ধর্ম ঠিক করে দিয়েছে। Browser, proxy, CDN আর crawler এই ধর্মের ওপর ভরসা করে আপনার অনুমতি ছাড়াই কাজ করে।

• Safe: client কোনো বদল চাইছে না, কাজটি মূলত শুধু পড়া। তাই যে কেউ আগেভাগে ডাকতে পারে।
• Idempotent: একই request একবার পাঠালে server-এ যে উদ্দেশ্যমূলক প্রভাব, বহুবার পাঠালেও তাই। উত্তর আলাদা হতে পারে, প্রভাব নয়।
• Cacheable: উত্তর জমিয়ে রেখে পরের request-এ দেওয়া যায়।

Idempotency-র আসল মূল্য বোঝা যায় নেটওয়ার্ক ভাঙলে। মিরপুরে এক ক্রেতা বোতাম চাপলেন, Wi-Fi কেটে গেল, উত্তর এল না। অনুরোধটি server-এ পৌঁছেছিল কি? Client জানে না। আবার পাঠানোই স্বাভাবিক। নিচে তিনবার retry করে PUT আর POST-এর ফল পাশাপাশি দেখুন।

// শেখার মডেল: node:http-এ হাতে লেখা, আসল বাজারঘর server নয়
const http = require("node:http");
const cart = new Map();
const orders = [];

const server = http.createServer((req, res) => {
  let out = { error: "no route" };
  if (req.method === "PUT" && req.url === "/api/cart/items/1") {
    cart.set(1, 2); // qty 2 বসানো: যতবারই হোক, ফল একই
    out = { productId: 1, qty: cart.get(1) };
  } else if (req.method === "POST" && req.url === "/api/orders") {
    orders.push({ id: orders.length + 1, totalPaisa: 84000 }); // প্রতিবার নতুন
    out = orders.at(-1);
  }
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify(out));
});

server.listen(0, "127.0.0.1", async () => {
  const base = `http://127.0.0.1:${server.address().port}/api`;
  for (let i = 1; i <= 3; i++) {
    const put = await fetch(`${base}/cart/items/1`, { method: "PUT" });
    const post = await fetch(`${base}/orders`, { method: "POST" });
    console.log(`try ${i}`, "PUT", await put.text(), "POST", await post.text());
  }
  console.log("cart lines:", cart.size, "| orders:", orders.length);
  console.log("to pay (paisa):", orders.length * 84000);
  server.close();
});

৫ · PUT বনাম PATCH, আর JSON Merge Patch

পর্ব ২৫-এ দুটি method-ই এসেছিল, পার্থক্যটি হালকাভাবে। এখন ঠিকভাবে। PUT বলে: “এই ঠিকানায় এখন থেকে ঠিক এই জিনিসটি থাকবে।” যা পাঠাননি, তা থাকবে না। PATCH (RFC 5789, ২০১০) বলে: “বর্তমান জিনিসে এই বদলগুলো করুন।”

PATCH-এর body কী রকম হবে, সেটি method ঠিক করে না। তাই একটি format লাগে। সবচেয়ে সহজটি JSON Merge Patch (RFC 7396, ২০১৪), যার media type application/merge-patch+json. তিনটি নিয়ম মনে রাখলেই হয়: উল্লেখ করা key বসে যায়, null মানে key মুছে ফেলা, আর array পুরোটাই বদলে যায়, তার এক টুকরো বদলানো যায় না।

// শেখার মডেল: PUT পুরো বদলায়, PATCH (RFC 7396) শুধু উল্লেখ করা অংশ
const http = require("node:http");
let product = { id: 2, name: "Soybean oil 1L", pricePaisa: 19000, stock: 3, tags: ["oil", "sale"] };

function mergePatch(target, patch) {
  const out = { ...target };
  for (const [key, value] of Object.entries(patch)) {
    if (value === null) delete out[key]; // null মানে key মুছে ফেলা
    else out[key] = value; // array হলে পুরোটাই বদলে যায়
  }
  return out;
}
const server = http.createServer(async (req, res) => {
  let raw = "";
  for await (const chunk of req) raw += chunk;
  const body = JSON.parse(raw);
  product = req.method === "PUT" ? { id: 2, ...body } : mergePatch(product, body);
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify(product));
});
server.listen(0, "127.0.0.1", async () => {
  const url = `http://127.0.0.1:${server.address().port}/api/products/2`;
  const send = async (method, body) => {
    const r = await fetch(url, { method, body: JSON.stringify(body) });
    console.log(method.padEnd(5), JSON.stringify(body), "\n  ->", await r.text());
  };
  await send("PATCH", { pricePaisa: 18500 });
  await send("PATCH", { tags: ["oil"], stock: null });
  await send("PUT", { name: "Oil", pricePaisa: 18000 });
  server.close();
});

“PATCH সবসময় idempotent নয়” কেন? {"stock":5} বসালে যতবারই হোক ৫। কিন্তু কেউ যদি নিজের format বানায়, যেমন {"increment":5}, প্রতিবার ৫ বাড়বে। RFC-ও তাই বলে: PATCH নিজে safe বা idempotent নয়, তবে এমনভাবে পাঠানো সম্ভব যাতে idempotent হয়। আরেকটি নিয়ম: হয় পুরো patch বসবে, নয়তো কিছুই না। আধাআধি বদল চলবে না।

Express 5-এর একটি সত্যিকারের ফাঁদ

Merge Patch-এর media type application/json নয়। express.json() ডিফল্টে শুধু application/json পড়ে। ফলে কোনো error ছাড়াই req.body খালি থাকে। এটি সত্যিকারের run, Express 5.3.0-তে, handler শুধু req.body ফেরত দেয়:

application/json               200 {"body":{"stock":1}}
application/merge-patch+json   200 {"body":"undefined"}

দ্বিতীয় সারিতে status 200, অথচ কিছুই আসেনি। এমন handler PATCH-এ কিছু না বদলেও “সফল” বলবে। সমাধান এক লাইনের:

app.use(express.json({
  type: ["application/json", "application/merge-patch+json"],
}));

৬ · সম্পর্ক — nested বনাম flat URL

একটি পণ্যের অনেক review. URL-এ এই সম্পর্ক কীভাবে দেখাবেন? দুটি পথ: nested URL, যেমন /api/products/1/reviews/1, আর flat URL, যেমন /api/reviews/1. ডেটাবেসে সম্পর্ক কীভাবে থাকে, সেটি পর্ব ৪১ (সম্পর্ক)-এ আসবে। URL-কে ডেটাবেসের ছবি হতে হবে না, তাকে client-এর কাজের ছবি হতে হবে।

আমাদের real run-এ পণ্য ১-এ review 1 আছে, পণ্য ২-এ review 2. তিনটি অনুরোধের পথ ধাপে ধাপে দেখুন।

review 1: {"id":1,"productId":1,"rating":5,"comment":"Good rice"}
review 2: {"id":2,"productId":2,"rating":3,"comment":"Leaky cap"}

$ curl localhost:3000/api/reviews/1
{"id":1,"productId":1,"rating":5,"comment":"Good rice",...}

$ curl -i localhost:3000/api/products/1/reviews/1
HTTP/1.1 200 OK
{"id":1,"productId":1,"rating":5,"comment":"Good rice",...}

$ curl -i localhost:3000/api/products/2/reviews/1
HTTP/1.1 404 Not Found
{"error":"not_found"}

$ curl localhost:3000/api/products/1/reviews
{"items":[{"id":1,"productId":1,...}],"count":1}

Filter দিয়েও সম্পর্ক বলা যায়: /api/reviews?productId=1. দুটি রূপ একই ডেটা দিলে একটিকে মূল ঠিকানা ধরুন। Review-এর Location-এ আমরা /api/reviews/1 দিয়েছি, একটি মূল ঠিকানা। URL-এ পণ্যের id থাকলেও ঠিকানা জানা মানে দেখার অনুমতি নয়। প্রতিটি route-এ মালিকানা যাচাই লাগে, নইলে broken access control. বাস্তব প্রয়োগ পর্ব ৪৮ (Permission)-এ।

৭ · যে কাজ CRUD-এ পড়ে না — অর্ডার বাতিল আর bulk

অর্ডার বাতিল কি update? আংশিক। এতে stock ফেরত আসে, কারণ জমা হয়, হয়তো টাকা ফেরত যায়। শুধু একটি field বদল নয়, একটি ব্যবসায়িক ঘটনা। তিনটি নকশা প্রচলিত:

“বাজারঘর” দ্বিতীয়টি নিচ্ছে, কারণ বাতিলের নিজের ডেটা আছে। তবে এটি নৈতিক প্রশ্ন নয়। তৃতীয়টিও বহু বাস্তব API-তে আছে, আর কিছু প্রকাশ্য API গাইড :cancel-এর মতো আলাদা custom method-ই সুপারিশ করে। আসল নিয়ম দুটি: এই কাজ POST হবে, GET নয়, আর একটি API-তে একই রীতি সর্বত্র চলবে।

পেছনে থাকে একটি state machine. আমাদের অর্ডার: placed থেকে shipped বা cancelled. status field client লেখে না, server ঘটনা দেখে বদলায়। নিচে real run-এর পুরো গল্প।

1PUT /cart/items/1 {"qty":2}2PUT /cart/items/2 {"qty":1}3POST /orders4POST /orders/1/cancellation5POST /orders/1/cancellation6POST /orders/2/shipment7POST /orders/2/cancellation

একটি ছোট প্রমাণ দেখুন যে client status লিখতে পারে না। /api/orders/1-এ PATCH route-ই নেই। Express নিজে থেকে OPTIONS-এর উত্তর দেয়, যা চুক্তি পরখ করার সহজ উপায়:

$ curl -i -X OPTIONS localhost:3000/api/orders/1
HTTP/1.1 200 OK
Allow: GET, HEAD
…
$ curl -i -X OPTIONS localhost:3000/api/products/1
HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, PUT
…

Bulk কাজ — একসাথে অনেক

ঈদের আগে ৫০০ পণ্যের দাম বদলাতে হবে। ৫০০টি PATCH ধীর। Bulk operation মানে এক request-এ অনেক কাজ। ঠিকানাটিও বিশেষ্য রাখা যায়: POST /api/price-updates. শুরুতেই দুটি প্রশ্নের উত্তর ঠিক করতে হয়।

• একটি ব্যর্থ হলে? হয় সব বাতিল (atomic, transaction-এ), নয়তো প্রতিটির আলাদা ফল।
• সর্বোচ্চ কতটি? সীমা না থাকলে একটি request-ই server আটকে দিতে পারে। আমাদের সীমা ১০০।

$ curl -X POST localhost:3000/api/price-updates -H "Content-Type: application/json" \
       -d '{"items":[{"id":1,"pricePaisa":41000},{"id":77,"pricePaisa":100},{"id":3,"pricePaisa":42.5}]}'
{"results":[{"id":1,"result":"updated"},{"id":77,"result":"not_found"},{"id":3,"result":"invalid_price"}]}

তিনটি জিনিস, তিন রকম ফল। এখানে প্রতিটির আলাদা ফল নেওয়া হয়েছে, আর তাই client-কে results পড়তেই হবে, status দেখে “সব ঠিক” ভাবা চলবে না। এমন আংশিক সাফল্যের status কী হবে, তা নিয়ে মতভেদ আছে, পর্ব ৩৩-এ দেখবেন। খুব বড় কাজে background job-ই ভালো, পর্ব ৬২-এ।

৮ · Representation — field, তারিখ, টাকা, ID আর envelope

REST-এর “R” এখানে। Server-এ ডেটা থাকে database-এ। Client পায় তার একটি representation, বাংলায় রূপ, সাধারণত JSON. Database column আর JSON field এক হতে হবে এমন নয়, আর password hash-এর মতো জিনিস কখনোই বাইরে যাবে না। এই রূপটিই চুক্তির সবচেয়ে বড় অংশ।

তারিখে 01/11/2026 লিখলে ১ নভেম্বর না ১১ জানুয়ারি, বলা যায় না। আগের সময়টিই বাংলাদেশে রাত ১১টা ১৬ মিনিট, কারণ এখানে UTC + ৬ ঘণ্টা: 2026-11-01T23:16:13.692+06:00 একই মুহূর্ত। Server UTC-তে পাঠাবে, দেখানোর সময় client স্থানীয় সময়ে বদলাবে। বাংলা তারিখ পর্ব ৫৯-এ।

টাকা কেন float নয়

৳১৯.৯০ দেখতে সরল। কিন্তু JavaScript-এর সংখ্যা দ্বিমিক ভগ্নাংশে থাকে (IEEE 754), আর দশমিকের ০.১-এর মতো অনেক মান দ্বিমিকে ঠিক লেখাই যায় না। ঠিক যেমন ১/৩ দশমিকে ০.৩৩৩… হয়ে চলতেই থাকে। হিসাব একসঙ্গে দেখুন।

// শেখার মডেল: একই বিক্রি, দুই রকম টাকার হিসাব, JSON হয়ে client-এ
const http = require("node:http");

const server = http.createServer((req, res) => {
  let takaFloat = 0;
  let paisaInt = 0;
  for (let sale = 0; sale < 1000; sale++) {
    takaFloat += 19.9; // ৳১৯.৯০ দশমিকে
    paisaInt += 1990; // একই দাম পয়সায়
  }
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ takaFloat, paisaInt }));
});

server.listen(0, "127.0.0.1", async () => {
  const r = await fetch(`http://127.0.0.1:${server.address().port}/api/sales`);
  const { takaFloat, paisaInt } = await r.json();
  console.log("1000 sales, float taka :", takaFloat);
  console.log("1000 sales, int paisa  :", paisaInt);
  console.log("equal to 19900 taka?   :", takaFloat === 19900, paisaInt === 1990000);
  console.log("3 x 19.9               :", 3 * 19.9);
  console.log("1.005 to 2 places      :", (1.005).toFixed(2));
  console.log("42 taka 50 paisa shown :", (4250 / 100).toFixed(2));
  server.close();
});

একটি বিনীত সংশোধন: পর্ব ২৫-এর price ছিল টাকায়, কারণ তখন বিষয়টি ছিল routing. চুক্তি এখন থেকে pricePaisa. ছাড় হিসাবে ভাগ এলে কীভাবে গোল করবেন, সেটি ব্যবসায়িক নিয়ম: ১৯,৯০০ পয়সার ৭.৫% = ১,৪৯২.৫ পয়সা। একটিই গোল করার নিয়ম একটিই জায়গায় রাখুন। ভিন্ন কৌশল হিসেবে কিছু API দামকে string ("199.00") পাঠায়, তাতেও float এড়ানো যায়। Database-এ integer বা DECIMAL, যেকোনোটি চলে, FLOAT নয়।

ID — সংখ্যা, string না UUID

শেষ সারির কারণটি পরীক্ষা করা। JavaScript-এ নিরাপদ পূর্ণসংখ্যার সীমা Number.MAX_SAFE_INTEGER = 9007199254740991. Node-এ আমাদের চালানো ফল: JSON.parse('9007199254740993') দিল 9007199254740992. Id-র শেষ অঙ্ক বদলে গেল, কোনো error ছাড়াই। অনুমান-কঠিন id-ও অনুমতির বিকল্প নয়।

Envelope বনাম সরাসরি JSON

একটি জিনিস ফেরত দিলে সরাসরি JSON যথেষ্ট: {"id":1,"status":"placed"}. তালিকায় ছোট envelope কাজে লাগে: {"items":[…],"count":2}. কারণ খোলা array-তে পরে nextCursor যোগ করার জায়গা নেই, অথচ object-এ নতুন key যোগ করলে পুরোনো client ভাঙে না। {"success":true,"data":{…}} ধাঁচের সবকিছু মোড়ানো envelope-ও বহু API-তে দেখবেন। এতে একই তথ্য দুবার থাকে, কারণ সাফল্যের খবর HTTP status আগেই দিয়েছে। “বাজারঘর”-এর নিয়ম: একক জিনিস সরাসরি, তালিকা items-এ।

Location header — নতুন জিনিসের ঠিকানা

POST-এ নতুন জিনিস হলে client জানতে চায় সেটি কোথায়। RFC 9110 বলে, 201-এর সঙ্গে server-এর Location পাঠানো উচিত। Express-এ res.status(201).location(url).json(data). সত্যিকারের run:

$ curl -i -X POST localhost:3000/api/products -H "Content-Type: application/json" \
       -d '{"sku":"SALT-1KG","name":"Salt 1kg","pricePaisa":4200,"stock":10}'
HTTP/1.1 201 Created
X-Powered-By: Express
Location: /api/products/3
Content-Type: application/json; charset=utf-8
…

{"id":3,"sku":"SALT-1KG","name":"Salt 1kg","pricePaisa":4200,"stock":10,"createdAt":"2026-11-01T17:16:13.692Z"}

Location-এর মান আপেক্ষিক হতে পারে, client সেটি request-এর ঠিকানার সঙ্গে মিলিয়ে নেয়। Client-কে id জুড়ে URL বানাতে হলো না, server-ই বলে দিল। আবার id, createdAt client পাঠায়নি, ওগুলো server-এর। তৈরির সময় client যে ঘরগুলো পাঠাতে পারে, শুধু সেগুলোই তোলা হচ্ছে, যাতে mass assignment না হয়।

৯ · বাজারঘরের পুরো API — কাগজ থেকে Express 5, আর একটি খারাপ API সারানো

এবার সব জোড়া দিই। প্রথমে কোড নয়, একটি পাতা। ক্রেতার গল্প, বিশেষ্য, সম্পর্ক, তারপর ঠিকানা আর method.

কাগজের সিদ্ধান্তগুলোর কারণ লিখে রাখুন, কারণ ছয় মাস পরে সেগুলোই কাজে লাগবে:

• কার্টের লাইন PUT: ঠিকানা client জানে, আর “qty ২ বসানো” idempotent.
• POST /api/orders-এ body নেই: দাম আর জিনিস server-ই কার্ট থেকে নেয়। Client-এর পাঠানো totalPaisa কখনো বিশ্বাস করা হয় না।
• অর্ডারের ভেতরে দামের কপি: unitPricePaisa কেনার মুহূর্তের দাম। পরে পণ্যের দাম বদলালেও পুরোনো অর্ডার বদলায় না।
• /api/cart-এ ক্রেতার id নেই: পরে login থেকে আসবে (পর্ব ৪৫)। এই demo-তে একজনই ক্রেতা।
• অর্ডারের তালিকা এখনো নেই: pagination ছাড়া তালিকা খোলা ঝুঁকি, পর্ব ৩৪।

এবার Express 5-এ। এই পর্বের জন্য চালানো সত্যিকারের run: Node 24.15.0, Express 5.3.0 (লেখার সময়ের সর্বশেষ stable), ডেটা memory-তে। পর্ব ২৫-এর মতো এখানেও পড়ার সুবিধায় port 3000 লেখা হয়েছে, বাকি সব হুবহু। পুরো ফাইলের মূল অংশ:

app.post("/api/products", (req, res) => {
  const { sku, name, pricePaisa, stock = 0, description } = req.body ?? {};
  if (!sku || !name || !isMoney(pricePaisa)) {
    return badRequest(res, "sku, name and integer pricePaisa are required");
  }
  const product = addProduct({ sku, name, pricePaisa, stock, description });
  res.status(201).location(`/api/products/${product.id}`).json(product);
});

// ঠিকানা client জানে, তাই PUT; একই qty বারবার পাঠালে ফল একই
app.put("/api/cart/items/:productId", (req, res) => {
  const productId = Number(req.params.productId);
  if (!db.products.has(productId)) return notFound(res);
  const { qty } = req.body ?? {};
  if (!Number.isInteger(qty) || qty < 1) return badRequest(res, "qty must be a positive integer");
  const created = !db.cart.has(productId);
  db.cart.set(productId, qty);
  res.status(created ? 201 : 200).json(cartView());
});

// অবস্থা বদল: client status লেখে না, ঘটনার resource তৈরি করে
app.post("/api/orders/:id/cancellation", (req, res) => {
  const order = findOrder(req, res);
  if (!order) return;
  if (order.status !== "placed") {
    return res.status(409).json({ error: "cannot_cancel", status: order.status });
  }
  for (const line of order.items) {
    const product = db.products.get(line.productId);
    if (product) product.stock += line.qty;
  }
  order.status = "cancelled";
  order.cancellation = { reason: req.body?.reason, cancelledAt: now() };
  res.status(201).location(`/api/orders/${order.id}/cancellation`).json(order);
});

এখানে যাচাই ইচ্ছা করেই হাতে লেখা ও ছোট, পূর্ণ schema পর্ব ২৭-এ, আর স্তরে ভাগ করা পর্ব ২৯-এ। আসল project-এ stock-এর বদল আর অর্ডার তৈরি এক transaction-এ হবে, পর্ব ৪৩-এ। PUT আর PATCH-এর real ফল দেখুন। শুরুতে পণ্য ২-এ description ছিল:

$ curl localhost:3000/api/products/2
{"id":2,"sku":"OIL-1L","name":"Soybean oil 1L","pricePaisa":19000,"stock":3,"createdAt":"2026-11-01T17:16:13.314Z","description":"1 litre bottle"}

$ curl -X PUT localhost:3000/api/products/2 -H "Content-Type: application/json" \
       -d '{"sku":"OIL-1L","name":"Soybean oil 1L","pricePaisa":18500,"stock":3}'
{"id":2,"sku":"OIL-1L","name":"Soybean oil 1L","pricePaisa":18500,"stock":3,"createdAt":"2026-11-01T17:16:13.314Z"}

$ curl -X PUT localhost:3000/api/products/2 -H "Content-Type: application/json" -d '{"pricePaisa":18500}'
{"error":"PUT needs the full product: sku, name, pricePaisa, stock"}

$ curl -X PATCH localhost:3000/api/products/2 -H "Content-Type: application/merge-patch+json" \
       -d '{"pricePaisa":18000,"description":null}'
{"id":2,"sku":"OIL-1L","name":"Soybean oil 1L","pricePaisa":18000,"stock":3,"createdAt":"2026-11-01T17:16:13.314Z"}

$ curl -X PATCH localhost:3000/api/products/2 -H "Content-Type: application/merge-patch+json" \
       -d '{"id":99,"pricePaisa":1}'
{"error":"not patchable: id"}

লক্ষ করুন, PUT-এ description চলে গেছে, কিন্তু createdAt আর id থেকে গেছে, কারণ ওগুলো server-এর ঘর। আর id PATCH করার চেষ্টা আটকে গেছে একটি allow-list-এ। DELETE দুবার ডেকেও আমাদের run-এ দুবারই 204 এসেছে। কেউ দ্বিতীয়বারে 404 দিলেও idempotent থাকে, কারণ দুই ক্ষেত্রেই পণ্যটি নেই।

একটি খারাপ API-র review

ধরুন একটি পুরোনো দোকানের (কাল্পনিক) API হাতে এল। এটি “চলে”, কিন্তু প্রতিটি সারিই একটি ঝুঁকি। ডান দিকে চুক্তির নতুন রূপ।

তবে মানুষ যে API ব্যবহার করছেন, তা একদিনে বদলানো যায় না, পুরোনো client ভাঙবে। নতুন ঠিকানা পাশে বসিয়ে ধীরে সরানোর পথ পর্ব ৩৫-এ।

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

AI কয়েক সেকেন্ডে পুরো CRUD API লিখে দেয়। কোড প্রায়ই চলেও। কিন্তু চলা আর ভালো চুক্তি এক নয়, আর চুক্তির ভুল পরে সারাতে সবচেয়ে দাম লাগে।

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

• প্রতিটি route নিজে একবার curl দিয়ে ডেকেছি, status আর header দেখেছি
• বাড়তি field পাঠিয়ে দেখেছি: id, status, totalPaisa কোনোটিই client বদলাতে পারে না
• প্রতিটি POST দুবার পাঠিয়ে ফল দেখেছি, আর একটি যোগফল হাতে মিলিয়েছি
• অচেনা package আর option আমার version-এর অফিসিয়াল docs-এ খুঁজেছি
• Prompt-এ কোনো আসল key, password বা গ্রাহকের ডেটা দিইনি
• অন্য ব্যবহারকারীর id দিয়ে ডেকে দেখেছি, ডেটা ফাঁস হয় না, আর একটি test লিখেছি