সরাসরি পর্বে যান
পর্ব ২৯ · ৮২-এর মধ্যে · মডিউল ৫

Tester-এর জন্য HTTP আর REST — method, status code আর JSON

HTTP and REST for Testers: Methods, Status Codes and JSON

Taught in Bangla, this lesson reads HTTP the way a tester does, from real curl -v output: request line, headers, blank line and body. It turns safe and idempotent method promises into test cases, picks the right status code (401, 403, 409, 422) for the Bazarghar demo shop, and hunts JSON bugs such as numbers as strings, null versus zero, broken Bangla encoding and times without a zone. A real curl run shows an Idempotency-Key stopping a double charge after a 504, until a seeded bug breaks it.

এই পর্বে যা শিখবেন

  • curl-এর -v output পড়ে request line, header, body আর status line আলাদা করে চেনা
  • প্রতিটি method-এর safe আর idempotent প্রতিশ্রুতি থেকে test case বের করা
  • বাজারঘরের বাস্তব পরিস্থিতিতে ঠিক status code বেছে নেওয়া, আর app-এর উত্তরের সাথে মিলিয়ে দেখা
  • JSON response-এ type, null, encoding আর সময়ের bug খুঁজে বের করা
  • curl, HTTPie আর browser-এর DevTools দিয়ে একটি API নিজের হাতে চালিয়ে দেখা, আর timeout-এর পরের retry যাচাই করা

১ · Tester-এর চোখে HTTP — একটি অনুরোধ, একটি উত্তর

বাজারঘরের অ্যাপে একজন ক্রেতা “রিভিউ জমা দিন” চাপলেন। পর্দায় সবুজ বার্তা এল। কিন্তু পর্দার পেছনে ব্রাউজার একটি বার্তা পাঠিয়েছে আর server একটি উত্তর দিয়েছে, যা হয়তো ভুল ছিল: ভুল status code, ভুল type-এর field, বা ভাঙা বাংলা লেখা। মডিউল ৫-এর বাকি পর্বগুলো এই বার্তাগুলোই যাচাই করে, তাই আগে বার্তাটি পড়তে শেখা দরকার।

কুরিয়ারে পার্সেল পাঠানোর কথা ভাবুন। কাউন্টারের ফর্মে প্রথমে লেখেন কী কাজ (“পাঠাতে চাই”) আর কোথায়। তারপর কয়েকটি ঘর: ওজন, প্রাপকের ফোন, ভঙ্গুর কি না। তারপর আসল পার্সেলটি। ফেরত আসে একটি রসিদ: ওপরে একটি সংক্ষিপ্ত ফল (“গ্রহণ করা হলো”, বা “ঠিকানা অসম্পূর্ণ”), কয়েকটি তথ্য, আর একটি tracking নম্বর। HTTP-র request আর response ঠিক এমন: কাজ আর ঠিকানা, কয়েকটি ঘর, তারপর মাল। একজন ভালো কাউন্টার-কর্মী যেমন রসিদের প্রতিটি ঘর মেলান, tester-ও তেমন উত্তরের প্রতিটি অংশ মেলান।

HTTP-র ইতিহাস, সংযোগ আর cache-এর বিস্তারিত পাবেন কম্পিউটার নেটওয়ার্ক কোর্সের পর্ব ৩৬-এ, আর Python দিয়ে API ডাকা Python কোর্সের পর্ব ৫০-এ। এখানে শুধু tester-এর দরকারি অংশ। নিচে বাজারঘরের app-এ একটি রিভিউ পাঠানোর সত্যিকারের run, Windows-এর সাথে আসা curl 8.13.0 দিয়ে। -v (verbose) দিলে curl পাঠানো লাইনগুলো > চিহ্ন দিয়ে আর পাওয়া লাইনগুলো < চিহ্ন দিয়ে দেখায়। Token ছোট করে … লেখা হয়েছে, আর তারিখ ও নিরাপত্তা-header-এর কয়েকটি লাইন বাদ দেওয়া হয়েছে:

$ curl -v -X POST http://127.0.0.1:8782/api/products/2/reviews \
    -H "Authorization: Bearer …" -H "Content-Type: application/json" \
    -d '{"stars":5,"text":"ডাল খুব ভালো, আবার কিনব।"}'
*   Trying 127.0.0.1:8782...
* Connected to 127.0.0.1 (127.0.0.1) port 8782
> POST /api/products/2/reviews HTTP/1.1
> Host: 127.0.0.1:8782
> User-Agent: curl/8.13.0
> Accept: */*
> Authorization: Bearer …
> Content-Type: application/json
> Content-Length: 83
>
* upload completely sent off: 83 bytes
< HTTP/1.1 201 Created
< content-length: 193
< content-type: application/json
<
{"id":7,"product_id":2,"customer_name":"মিতু রহমান","stars":5,"text":"ডাল খুব ভালো, আবার কিনব।","created_at":"2026-11-16T17:30:09+06:00"}

এই run-এর app হলো কোর্সের শেয়ার করা বাজারঘর app (FastAPI-তে লেখা, MIT licence), যা নিজের যন্ত্রে 127.0.0.1-এ চলে, বাইরের কোনো জায়গায় যায় না, আর wallet-এর লেনদেন একটি নকল gateway-তে হয়। নিচের stepper-এ একই বার্তা ভাগে ভাগে দেখুন।

1POST …/2/reviews HTTP/1.12Host: 127.0.0.1:87823Authorization: Bearer …4Content-Type: …/json5Content-Length: 8367{"stars":5,"text":"ডাল খুব…"}8HTTP/1.1 201 Created9content-type: …/json10content-length: 1931112{"id":7,...,"stars":5,...}
এই ধাপে
অংশ
Tester-এর প্রশ্ন
  1. Request line. প্রথম লাইনে তিনটি জিনিস: method (POST, অর্থাৎ নতুন কিছু জমা), target বা path (কোন রিভিউ-তালিকায়), আর HTTP version. ভুল method বা ভুল path-এর bug এখানেই ধরা পড়ে।
  2. Header. প্রতিটি header একটি “নাম: মান” জোড়া। Host বলে কোন server, Authorization বলে কে পাঠাচ্ছেন, Content-Type বলে body-র ধরন, Content-Length বলে body কত byte. Header-এর নামে বড়-ছোট হাতের অক্ষরে পার্থক্য নেই।
  3. ফাঁকা লাইন, তারপর body. একটি ফাঁকা লাইন header শেষ হওয়ার সংকেত। তারপর body, এখানে JSON. লক্ষ করুন, লেখাটি ২৪ অক্ষরের, কিন্তু body ৮৩ byte: বাংলার প্রতিটি অক্ষর UTF-8-এ তিন byte নেয়। §৪-এ এর ফল দেখবেন।
  4. Status line. উত্তরের প্রথম লাইনে version, তিন অঙ্কের status code আর একটি ছোট বর্ণনা। 201 Created মানে নতুন কিছু তৈরি হয়েছে। Test-এর প্রথম assertion প্রায় সবসময় এটি।
  5. Response header. content-type: application/json জানায় body JSON; content-length জানায় তার আকার। Server ছোট হাতের অক্ষরে header লিখেছে, যা পুরোপুরি বৈধ। আসল output-এ আরও কয়েকটি নিরাপত্তা-header ছিল, যা পর্ব ৫২-৫৩-এর security testing অংশে কাজে লাগবে।
  6. Response body. নতুন রিভিউটি ফেরত এল: id 7, stars একটি সংখ্যা (string নয়), লেখা অপরিবর্তিত বাংলায়, আর সময় ঢাকার time zone-সহ। এই প্রতিটি মিলিয়ে দেখাই API testing-এর মূল কাজ।

বার্তাটি যে আসলেই সাধারণ লেখা, তা নিজে বানিয়ে দেখা যায়। নিচের block একটি ছোট builder দিয়ে ঠিক ওপরের request-টি byte ধরে তৈরি করে (\r\n হলো HTTP-র লাইন-শেষ), তারপর app-এর একটি সত্যিকারের 422 উত্তর (curl দিয়ে রেকর্ড করা) ভেঙে অংশগুলো আলাদা করে। এই পাতায় কোনো network ডাকা হয় না।

import json

def build_request(method, target, headers, body=None):
    data = b""
    if body is not None:                       # JSON body, always UTF-8
        data = json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
        headers = {**headers, "Content-Type": "application/json",
                   "Content-Length": str(len(data))}      # bytes, not letters
    head = f"{method} {target} HTTP/1.1\r\n"
    head += "".join(f"{k}: {v}\r\n" for k, v in headers.items()) + "\r\n"
    return head.encode("ascii") + data

def parse_response(raw):
    head, _, body = raw.partition(b"\r\n\r\n")  # blank line ends the headers
    status_line, *lines = head.decode("ascii").split("\r\n")
    version, code, reason = status_line.split(" ", 2)
    headers = {k.strip().lower(): v.strip() for k, v in (x.split(":", 1) for x in lines)}
    return int(code), reason, headers, body

review = {"stars": 5, "text": "ডাল খুব ভালো, আবার কিনব।"}
req = build_request("POST", "/api/products/2/reviews",
                    {"Host": "127.0.0.1:8782", "Authorization": "Bearer FAKE"}, review)
print(req.decode("utf-8").replace("\r\n", "\\r\\n\n"))
print("\ntext letters:", len(review["text"]), "| body bytes:", len(req.partition(b"\r\n\r\n")[2]))

# a 422 recorded from the real app (curl -i), turned back into parts
raw = (b"HTTP/1.1 422 Unprocessable Entity\r\ncontent-length: 107\r\n"
       b"content-type: application/json\r\n\r\n"
       b'{"detail":[{"type":"int_type","loc":["body","stars"],'
       b'"msg":"Input should be a valid integer","input":"5"}]}')
code, reason, h, body = parse_response(raw)
print(code, reason, "| JSON?", h["content-type"] == "application/json",
      "| length ok?", int(h["content-length"]) == len(body))
err = json.loads(body)["detail"][0]
print(err["loc"], "->", err["msg"], "| sent:", repr(err["input"]))

আসল আউটপুট (ব্রাউজারের Python):

POST /api/products/2/reviews HTTP/1.1\r\n
Host: 127.0.0.1:8782\r\n
Authorization: Bearer FAKE\r\n
Content-Type: application/json\r\n
Content-Length: 83\r\n
\r\n
{"stars":5,"text":"ডাল খুব ভালো, আবার কিনব।"}

text letters: 24 | body bytes: 83
422 Unprocessable Entity | JSON? True | length ok? True
['body', 'stars'] -> Input should be a valid integer | sent: '5'

নিজের বানানো request-এর Content-Length: 83 হুবহু curl-এর পাঠানো মানের সাথে মিলেছে, কারণ দুটিই byte গোনে। কেউ যদি লেখার অক্ষর গুনে (২৪) বা Python-এর len(str) দিয়ে (৪৫) length বসান, server body কেটে পড়বে বা আরও byte-এর অপেক্ষায় আটকে থাকবে। দ্বিতীয় অংশে app-এর একটি আসল 422 ভাঙা হলো: header-এর length আর body-র byte মেলে, আর ভুলের জায়গা ['body', 'stars'], কারণ পাঠানো হয়েছিল string '5', সংখ্যা 5 নয়। Error-এর ভেতরে loc থাকা একজন tester-এর জন্য উপহার: bug report-এ সরাসরি লেখা যায় কোন field.

২ · Method — safe, idempotent আর tester-এর প্রশ্ন

HTTP-র প্রতিটি method একটি প্রতিশ্রুতি দেয়, যা মান-নথিতে লেখা (বর্তমানে RFC 9110, ২০২২ সালের)। দুটি প্রতিশ্রুতি tester-এর কাছে সবচেয়ে দরকারি। Safe মানে method-টি server-এর অবস্থা বদলানোর উদ্দেশ্যে নয়, শুধু পড়ার জন্য। Idempotent মানে একই request একবার পাঠানো আর দশবার পাঠানোর ফল server-এর অবস্থায় একই। মোবাইল রিচার্জের সাথে মিলিয়ে দেখুন: ব্যালেন্স দেখা safe, যতবার খুশি দেখুন। “ব্যালেন্স ঠিক ১০০ টাকা করো” ধরনের আদেশ idempotent, দুবার দিলেও ১০০। কিন্তু “১০০ টাকা রিচার্জ করো” দুবার গেলে দুবার টাকা কাটে; এটি idempotent নয়।

MethodSafe?Idempotent?বাজারঘরেTester-এর test
GETহ্যাঁহ্যাঁ/api/products/1দুবার ডাকলে একই ফল; ডাকার পরে কিছু বদলায়নি
HEADহ্যাঁহ্যাঁGET-এর header, body ছাড়াheader GET-এর সাথে মেলে কি না
OPTIONSহ্যাঁহ্যাঁকোন method চলে, জানতেCORS-এর preflight (§৬)
POSTনানা/api/orders, /payদুবার পাঠালে দুটি অর্ডার বা দুবার টাকা? (§৭)
PUTনাহ্যাঁ/api/cart/items/3 {"qty":2}দুবার পাঠালেও qty 2, 4 নয়
PATCHনানিশ্চিত নয়(এই app-এ নেই)“যোগ করো” ধরনের patch দুবারে দুবার যোগ করে
DELETEনাহ্যাঁ/api/cart/items/3দ্বিতীয়বারে অবস্থা একই; উত্তর 404 হতে পারে

দুটি সূক্ষ্ম কথা মনে রাখুন। প্রথম, idempotent মানে server-এর অবস্থা একই থাকে, উত্তর একই থাকা নয়: একটি জিনিস দ্বিতীয়বার মুছতে গেলে প্রথমবার 200, পরের বার 404 আসা স্বাভাবিক। দ্বিতীয়, এগুলো প্রতিশ্রুতি, প্রাকৃতিক নিয়ম নয়। কোনো developer চাইলে GET দিয়েও অর্ডার বাতিল করার endpoint বানাতে পারেন; তখন একটি search engine-এর crawler বা ব্রাউজারের আগাম-লোড সেই link ছুঁয়ে অর্ডার বাতিল করে দিতে পারে। তাই tester-এর একটি সহজ test: প্রতিটি GET-এর আগে আর পরে অবস্থা মিলিয়ে দেখা।

ভুল method পাঠালে কী হয়, সেটিও একটি test. বাজারঘরে পণ্য মোছার কোনো API নেই; সত্যিকারের run:

$ curl -i -X DELETE http://127.0.0.1:8782/api/products/1
HTTP/1.1 405 Method Not Allowed
allow: GET
content-type: application/json

{"detail":"Method Not Allowed"}

405 সঠিক উত্তর, আর সাথে allow: GET header জানিয়ে দিল এই path-এ কোন method চলে। এটি মান-নথির চাওয়া আচরণ, তাই একটি ভালো negative test: প্রতিটি endpoint-এ অন্তত একটি অনুমোদিত-নয় এমন method পাঠিয়ে 405 আর Allow দুটিই যাচাই করা। Developer-এর ভুলে কোনো endpoint যদি অজানা method-এ 200 দেয়, বা 500-এ ভেঙে পড়ে, এই test তা ধরবে।

৩ · Status code — পাঁচ পরিবার আর বারবার দেখা ষোলোটি

Status code তিন অঙ্কের, আর প্রথম অঙ্কটি পরিবার বলে দেয়: 1xx তথ্য, 2xx সফল, 3xx অন্য জায়গায় যান, 4xx অনুরোধে সমস্যা (client-এর দিক), 5xx server-এর সমস্যা। Tester-এর জন্য এই ভাগের একটি বড় অর্থ আছে: 4xx পেলে একই request আবার পাঠিয়ে লাভ নেই, অনুরোধ বদলাতে হবে; 5xx-এর কিছু ক্ষেত্রে পরে আবার চেষ্টা করা যায়। আর একটি নিয়ম প্রায় সবখানে খাটে: যেকোনো 500 একটি bug. ব্যবহারকারী যত অদ্ভুত input-ই দিন, server ভেঙে পড়ার বদলে একটি অর্থপূর্ণ 4xx দেবে, এটিই প্রত্যাশা।

Codeমানেবাজারঘরে উদাহরণএই app-এ দেখা?
200 OKসফল, body-তে ফলপণ্যের তথ্য, quoteহ্যাঁ
201 Createdনতুন resource তৈরিনতুন অর্ডার, নতুন রিভিউহ্যাঁ
204 No Contentসফল, body নেইমোছার পরে প্রায়ইনা; এই app মুছে 200 আর নতুন cart দেয়
301 Moved Permanentlyস্থায়ীভাবে নতুন ঠিকানাপুরোনো URL থেকে নতুনেনা; HTML login-এ 303 আছে
304 Not Modifiedআপনার কাছের কপিই চলবেETag মিললেনা; app cache-control: no-store পাঠায়
400 Bad Requestঅনুরোধটিই অচলখালি cart-এ অর্ডার, URL-এ কাঁচা বাংলাহ্যাঁ
401 Unauthorizedপরিচয় নেই বা ভুলtoken ছাড়া অর্ডার-তালিকাহ্যাঁ, WWW-Authenticate-সহ
403 Forbiddenপরিচয় জানা, অনুমতি নেইdelivered নয় এমন অর্ডারের রিভিউহ্যাঁ
404 Not Foundনেই (বা আপনার জন্য নেই)পণ্য 999, অন্যের অর্ডারহ্যাঁ
409 Conflictএখনকার অবস্থার সাথে সংঘাতshipped অর্ডার বাতিল, স্টক কমহ্যাঁ
415 Unsupported Media Typebody-র ধরন অচলJSON-এর বদলে plain textনা; app 422 দেয় (§৫)
422 Unprocessable Contentবোঝা গেছে, মান অচল"stars":"5", qty 11হ্যাঁ
429 Too Many Requestsখুব বেশি অনুরোধlogin-এ বারবার ভুল passwordনা; app-এ rate limit নেই
500 Internal Server Errorserver-এর অপ্রত্যাশিত ভাঙনকখনোই প্রত্যাশিত নয়না (দেখলে bug report)
502 Bad Gatewayমাঝের proxy পেছনের server থেকে অচল উত্তর পেলapp বন্ধ, সামনে nginx চালুনা; সামনে কোনো proxy নেই
503 Service Unavailableএখন সেবা দিতে পারছে নারক্ষণাবেক্ষণ, অতিরিক্ত চাপনা

তালিকার বাইরে এই app আরও তিনটি code দেয়: 405 (§২), wallet প্রত্যাখ্যান করলে 402, আর wallet সময়মতো উত্তর না দিলে 504 Gateway Timeout. “এই app-এ দেখা?” কলামটি একটি অভ্যাস: যে code system দেয়, তা নথিতে (OpenAPI) আছে কি না যাচাই করা। 429 না থাকাও একটি পর্যবেক্ষণ: login-এ সীমাহীন চেষ্টা নিরাপত্তার ঝুঁকি।

কোন code কোথা থেকে আসে, তা জানলে bug-এর জায়গা দ্রুত খোঁজা যায়। একটি request server-এর ভেতরে কয়েকটি স্তর পার হয়, আর প্রতিটি স্তর নিজের ধরনের “না” বলে:

কোন স্তর কোন status code ফেরত দেয়

ওপর থেকে নিচে একটি request-এর পথ; প্রতিটি স্তরে আটকে গেলে ডানের code

Which layer returns which HTTP status code Client: browser · curl CORS (শুধু browser-এ) HTTP parserroute আর method পরিচয় (token)schema যাচাই নিয়ম আর মালিকানাবাইরের সেবা (wallet) সফল: 200 · 201 browser থামায় 400404 · 405 401422 403·404·409402 · 504
ছবি ২৯.১ — একই “ভুল” ভিন্ন স্তরে ভিন্ন code পায়। "stars":"5" schema-স্তরে 422; একই রিভিউ অন্যের অর্ডারে নিয়ম-স্তরে 403. CORS server-এর স্তর নয়: curl সেটি মানে না, শুধু browser মানে।

ছবির ক্রমটি tester-এর জন্য একটি কৌশলও দেয়: একটি negative test-এ একবারে একটিই ভুল। Token ছাড়া, ভুল type-এর মান দিয়ে, অন্যের অর্ডারে একসাথে পাঠালে প্রথম স্তরেই (401) থেমে যাবে, বাকি দুটি স্তর কখনো যাচাই হবে না। এটি পর্ব ০৭-এর “প্রতি test-এ একটি invalid partition” নিয়মেরই HTTP রূপ। নিচের stepper-এ বাজারঘরের পাঁচটি পরিস্থিতিতে ঠিক code বেছে নিন, তারপর app কী দিল দেখুন।

ঘটনা আর সিদ্ধান্ত
ঘটনা
প্রার্থী
বাছাই
App দিল
  1. নতুন অর্ডার। কাজ সফল, আর নতুন একটি resource তৈরি হলো, তাই 200 নয়, 201. Body-তে নতুন অর্ডার, id 8. একটি পর্যবেক্ষণ: REST-এর রীতি অনুযায়ী 201-এর সাথে নতুন resource-এর ঠিকানা Location header-এ দেওয়া ভালো; এই app দেয় না। এটি bug নয়, একটি প্রশ্ন যা দলকে জিজ্ঞেস করবেন।
  2. অন্যের অর্ডার। মিতু লগইন করা, তাই 401 নয়। স্বাভাবিক উত্তর মনে হয় 403, কিন্তু তাতে একটি তথ্য ফাঁস হয়: “অর্ডার ৫ আছে, শুধু আপনার নয়।” তাই বাজারঘর ইচ্ছা করে 404 দেয়, যাতে কেউ id বদলে বদলে অন্যদের অর্ডার গুনতে না পারে। এটি নথিতে লেখা সিদ্ধান্ত; test এই সিদ্ধান্তটিই যাচাই করে।
  3. Shipped অর্ডার বাতিল। অনুরোধের গঠন ঠিক (400 নয়), রাফির নিজের অর্ডার (403 নয়); সমস্যা হলো অর্ডারের এখনকার অবস্থা। তাই 409 Conflict. Body-তে current_status: shipped আছে, যা পর্ব ১০-এর state table-এর অবৈধ transition-টিই।
  4. String-এ stars. JSON ঠিকভাবে পড়া গেছে, তাই 400-এর চেয়ে 422 বেশি নির্দিষ্ট: গঠন ঠিক, মান অচল। কিছু দল এখানে 400 দেয়; দুটিই চলে, শর্ত একটাই, পুরো API-তে একই রীতি। App-এর body-তে loc: ["body","stars"].
  5. Token ছাড়া। পরিচয়ই নেই, তাই 401, আর মান-নথি অনুযায়ী সাথে WWW-Authenticate header, যা জানায় কোন পদ্ধতিতে পরিচয় দিতে হবে (Bearer). পাঁচটি ঘটনাতেই app প্রত্যাশিত code দিয়েছে; নিচের block এগুলো আর একটি অমিল একসাথে যাচাই করে।

নিচের block দুটি ছোট helper বানায়, যা পরের পর্বের test-এ কাজে লাগবে: family() code-এর পরিবার বলে, আর may_auto_retry() ঠিক করে একটি ব্যর্থ request নিজে থেকে আবার পাঠানো নিরাপদ কি না। প্রথম তালিকার “actual” মানগুলো app-এর সত্যিকারের run থেকে নেওয়া। শেষ সারিটি আমাদের প্রত্যাশা: ভুল Content-Type-এ মান-নথির সবচেয়ে মানানসই উত্তর 415.

FAMILY = {1: "info", 2: "success", 3: "redirect", 4: "client error", 5: "server error"}
SAFE, IDEMPOTENT = {"GET", "HEAD", "OPTIONS"}, {"GET", "HEAD", "OPTIONS", "PUT", "DELETE"}

def family(code):
    return FAMILY.get(code // 100, "INVALID")

def may_auto_retry(method, code, has_key=False):
    """Retry only if the same request again cannot do harm twice."""
    if code not in (429, 502, 503, 504):
        return False                      # 4xx: the request itself is wrong
    return method in IDEMPOTENT or has_key

# (case, method, expected by the spec, actual from the real app run)
cases = [
    ("new order created",          "POST", 201, 201),
    ("someone else's order",       "GET",  404, 404),
    ("cancel a shipped order",     "POST", 409, 409),
    ("stars sent as a string",     "POST", 422, 422),
    ("no token on /api/orders",    "GET",  401, 401),
    ("JSON sent as text/plain",    "POST", 415, 422),
]
for name, m, want, got in cases:
    mark = "ok  " if want == got else "DIFF"
    print(f"{mark} {name:26} want {want} got {got} ({family(got)})")

print()
for m, code, key in [("GET", 503, False), ("POST", 504, False),
                     ("POST", 504, True), ("POST", 422, True), ("PUT", 502, False)]:
    print(f"{m:4} {code} key={key!s:5} -> retry? {may_auto_retry(m, code, key)}")
print("family(299):", family(299), "| family(600):", family(600))

আসল আউটপুট (ব্রাউজারের Python):

ok   new order created          want 201 got 201 (success)
ok   someone else's order       want 404 got 404 (client error)
ok   cancel a shipped order     want 409 got 409 (client error)
ok   stars sent as a string     want 422 got 422 (client error)
ok   no token on /api/orders    want 401 got 401 (client error)
DIFF JSON sent as text/plain    want 415 got 422 (client error)

GET  503 key=False -> retry? True
POST 504 key=False -> retry? False
POST 504 key=True  -> retry? True
POST 422 key=True  -> retry? False
PUT  502 key=False -> retry? True
family(299): success | family(600): INVALID

পাঁচটি মিল, একটি অমিল। অমিলটি bug কি না, সেটি নির্ভর করে বাজারঘরের নথি কী বলে তার ওপর; §৫-এ এর বিচার। Retry-র সারিগুলো পড়ুন: GET-এ 503 এলে আবার চাওয়া নিরাপদ, কারণ GET কিছু বদলায় না। POST-এ 504 এলে key ছাড়া আবার পাঠানো নিরাপদ নয়: প্রথমটি হয়তো কাজ করে ফেলেছে। একই POST key-সহ হলে নিরাপদ। আর 422-তে কখনো retry নয়, key থাকলেও: একই ভুল অনুরোধ একশোবার পাঠালেও একই উত্তর আসবে। family(600) বলছে INVALID: ৫৯৯-এর বেশি কোনো code-কে test-এ বৈধ ধরা উচিত নয়।

৪ · JSON আর data-র চেনা bug — string সংখ্যা, null, বাংলা লেখা আর সময়

প্রায় সব আধুনিক API-র body JSON-এ। JSON-এ মান মাত্র ছয় ধরনের: object ({}), array ([]), string, number, true/false আর null. তারিখ বা টাকার জন্য আলাদা ধরন নেই, তাই সেগুলো কীভাবে লেখা হবে তা দলের চুক্তি। এখানেই সবচেয়ে বেশি নীরব bug জন্মায়: পর্দায় সব ঠিক দেখায়, কিন্তু অন্য একটি app (মোবাইল অ্যাপ, হিসাব বিভাগের script) ভুল বোঝে। চারটি পরিবার চিনে রাখুন।

সংখ্যা যখন string

"price":"230" দেখতে ঠিক। কিন্তু JavaScript-এ "230" + 120 হয় "230120", ৩৫০ নয়; delivery যোগ করতে গিয়ে বিল কয়েকশো গুণ। উল্টো দিকে বাজারঘর "stars":"5" নেয় না (422), যা কঠোর এবং ঠিক।

type

null, শূন্য আর অনুপস্থিত

চা পাতার "average": null মানে “এখনও রিভিউ নেই”, আর 0 মানে “গড় শূন্য তারা”। দুটি আলাদা তথ্য। Field পুরোপুরি বাদ পড়া তৃতীয় অবস্থা। প্রতিটির জন্য আলাদা test case.

অর্থ

বাংলা লেখার encoding

JSON-এর মান-নথি (RFC 8259, ২০১৭) বলে, system-এর বাইরে আদান-প্রদানে JSON হবে UTF-8. কোথাও UTF-8-এর byte-কে অন্য encoding ধরে পড়লে “মিনিকেট” হয়ে যায় মি..., যাকে বলে mojibake.

encoding

সময় আর time zone

বাজারঘর লেখে 2026-11-16T17:30:09+06:00: ISO 8601 ধাঁচ, শেষে ঢাকার অফসেট। 2026-11-16 17:30:09 লিখলে কোন অঞ্চলের সময়, বোঝার উপায় নেই; UTC-তে চলা server রাত ১২টার আশেপাশে ভুল দিনের অর্ডার দেখাবে (পর্ব ১৪-এর time zone ফাঁদ)।

সময়

আরও দুটি ছোট ফাঁদ। রিভিউর গড়ের জন্য app দুটি field দেয়: "average": 4.3 (সংখ্যা, হিসাবের জন্য) আর "average_display": "4.3" (string, দেখানোর জন্য)। Tester যাচাই করেন দুটি সবসময় মেলে। দ্বিতীয়, টাকা: বাজারঘর টাকা পূর্ণ সংখ্যায় রাখে (961), তাই floating point-এর 0.1 + 0.2 ধরনের সমস্যা আসে না।

বাংলা লেখার সবচেয়ে চমকপ্রদ bug-টি URL-এ। ব্রাউজারের ঠিকানার ঘরে “চাল” লিখে খুঁজলে ব্রাউজার নিজেই প্রতিটি byte-কে %E0%A6%9A ধাঁচে লিখে পাঠায়, যাকে বলে percent-encoding. কিন্তু হাতে লেখা script বা test অনেক সময় তা করে না। সত্যিকারের run, একই খোঁজ দুইভাবে:

$ curl -i "http://127.0.0.1:8782/api/products?q=চাল"
HTTP/1.1 400 Bad Request
content-type: text/plain; charset=utf-8
Connection: close

Invalid HTTP request received.

$ curl -s -G --data-urlencode "q=চাল" -w "\n%{url_effective}\n" http://127.0.0.1:8782/api/products
{"items":[{"id":1,"sku":"RICE-5KG","name_bn":"মিনিকেট চাল ৫ কেজি", … ,"category":"চাল",
"rating":{"average":4.3,"count":4}}],"total":1,"q":"চাল","limit":50,"offset":0}
http://127.0.0.1:8782/api/products?q=%e0%a6%9a%e0%a6%be%e0%a6%b2

প্রথমবার Windows-এর curl কাঁচা UTF-8 byte পাঠিয়েছে, আর server-এর HTTP parser (uvicorn) একে অচল request ধরে 400 দিয়েছে; উত্তরটি JSON-ও নয়, সাধারণ লেখা। দ্বিতীয়বার --data-urlencode নিজে encode করেছে, আর শেষ লাইনে দেখা যাচ্ছে আসলে কী গেছে: “চাল”-এর তিনটি অক্ষর নয় byte, অর্থাৎ ৯টি %xx. শিক্ষা দুটি: test-এর HTTP client যেন সবসময় encode করে, আর app-এর বাংলা খোঁজের test-এ অন্তত একটি বাংলা শব্দ থাকা চাই।

নিচের block একটি ছোট “data bug” checker. ভালো নমুনাটি app-এর সত্যিকারের GET /api/products/10 (চা পাতা) উত্তর থেকে, সাথে একটি রিভিউর created_at. খারাপ নমুনায় একই পণ্যে পাঁচটি seeded data bug বসানো, যেমনটি একটি ভুল build বা ভুলভাবে লেখা serializer দিতে পারে:

import json
from datetime import datetime

# recorded from the real app: GET /api/products/10 (tea) and a review's created_at
good = json.loads('{"id":10,"name_bn":"চা পাতা ৪০০ গ্রাম","price":230,"stock":0,'
                  '"in_stock":false,"rating":{"average":null,"count":0},'
                  '"created_at":"2026-10-24T18:00:00+06:00"}')
# the same product from a buggy build (seeded data bugs)
bad = dict(good, price="230", stock=None, in_stock="false",
           name_bn="চা পাতা ৪০০ গ্রাম".encode("utf-8").decode("latin-1"),
           created_at="2026-10-24 18:00:00")

RULES = {"id": int, "price": int, "stock": int, "in_stock": bool, "name_bn": str}

def data_bugs(p):
    found = []
    for field, kind in RULES.items():
        v = p.get(field)
        if v is None:
            found.append(f"{field}: null, but the contract says {kind.__name__}")
        elif type(v) is not kind:        # bool is a subclass of int: check exactly
            found.append(f"{field}: {type(v).__name__} {v!r}, expected {kind.__name__}")
    if "à¦" in p["name_bn"]:
        found.append("name_bn: mojibake (UTF-8 bytes read as Latin-1)")
    if datetime.fromisoformat(p["created_at"]).tzinfo is None:
        found.append("created_at: no time zone (+06:00 or Z missing)")
    if p["rating"]["average"] is not None and p["rating"]["count"] == 0:
        found.append("rating: average without any review")
    return found

for name, product in [("good", good), ("bad", bad)]:
    bugs = data_bugs(product)
    print(f"{name}: {len(bugs)} data bug(s)")
    for b in bugs:
        print("  -", b)

আসল আউটপুট (ব্রাউজারের Python):

good: 0 data bug(s)
bad: 5 data bug(s)
  - price: str '230', expected int
  - stock: null, but the contract says int
  - in_stock: str 'false', expected bool
  - name_bn: mojibake (UTF-8 bytes read as Latin-1)
  - created_at: no time zone (+06:00 or Z missing)

পাঁচটি seeded bug-ই ধরা পড়ল, আর আসল উত্তরে একটিও নেই। কয়েকটি জিনিস লক্ষ করুন। "false" string-টি সবচেয়ে বিপজ্জনক: JavaScript বা Python-এ খালি নয় এমন string “সত্য” ধরা হয়, তাই if (p.in_stock) স্টক-শূন্য চা-কে “আছে” দেখাবে। Type যাচাইয়ে type(v) is not kind লেখা হয়েছে, isinstance নয়, কারণ Python-এ True একটি int-ও; নইলে "price": true পাস করে যেত। আর চা-র "average": null আসল উত্তরে বৈধ, কারণ count শূন্য। শেষ নিয়মটি উল্টো অবস্থা খোঁজে: রিভিউ নেই অথচ গড় আছে। এই checker হাতে লেখা নিয়ম; পর্ব ৩১ (Code দিয়ে API testing — pytest, httpx আর JSON Schema)-এ একই কাজ JSON Schema আর app-এর OpenAPI নথি দিয়ে করবেন।

৫ · REST resource, path বনাম query, আর content negotiation

REST শব্দটি এসেছে Roy Fielding-এর ২০০০ সালের PhD গবেষণাপত্র থেকে, যেখানে তিনি ওয়েবের স্থাপত্যের নীতিগুলো বর্ণনা করেন। আজ “REST API” বলতে সাধারণত বোঝায়: জিনিসগুলো resource, প্রতিটির একটি URL, আর তার ওপর কাজ HTTP method দিয়ে। নকশার পুরো আলোচনা আছে Full-Stack কোর্সের পর্ব ৩২-এ। Tester-এর দরকার এই রীতি থেকে প্রত্যাশা বের করা:

URL-এর অংশউদাহরণকাজTest-এর ভাবনা
Collection/api/ordersঅর্ডারের তালিকা; POST-এ নতুনখালি তালিকা [], null নয়
Path parameter/api/orders/8নির্দিষ্ট একটি resourceনা-থাকা id, অন্যের id, abc, -1, 0
Sub-resource/api/products/1/reviewsএকটি পণ্যের রিভিউনা-থাকা পণ্যে 404, খালি তালিকা নয়
Query parameter?q=tea&limit=2খোঁজা, ছাঁকা, পাতা ভাগবাংলা শব্দ, খালি q, limit=0, সীমার বাইরে
Action/api/orders/8/payযে কাজ CRUD-এ পড়ে নাদুবার পাঠানো (§৭), ভুল অবস্থায় 409

সহজ নিয়ম: কোন জিনিস তা path বলে, কীভাবে দেখাব (কোনগুলো, কতটি, কোন ক্রমে) তা query বলে। তাই না-থাকা path-এ 404 আসে, কিন্তু কিছু না মেলা খোঁজে 200 আর খালি তালিকা: ?q=chal দিলে বাজারঘর দেয় {"items":[],"total":0,...}. Tester-এর জন্য দুটিই প্রত্যাশিত, আর এদের উল্টে যাওয়া (খোঁজে কিছু না পেলে 404) একটি সাধারণ নকশা-bug. Path-এ ভুল type দিলে কী হয়, সত্যিকারের run:

$ curl -i http://127.0.0.1:8782/api/products/999
HTTP/1.1 404 Not Found
content-type: application/json

{"detail":{"code":"product_not_found","message":"পণ্যটি পাওয়া যায়নি"}}

$ curl -i http://127.0.0.1:8782/api/products/abc
HTTP/1.1 422 Unprocessable Entity
content-type: application/json

{"detail":[{"type":"int_parsing","loc":["path","product_id"],"msg":"Input should be a valid
integer, unable to parse string as an integer","input":"abc"}]}

লক্ষ করুন দুটি error-এর আকার আলাদা: ব্যবসার ভুলে detail একটি object (code আর message), schema-র ভুলে detail একটি array. বাজারঘরের নথিতে দুটি আকারই লেখা আছে, তাই এটি bug নয়; কিন্তু client-এর কোডকে দুটিই সামলাতে হবে, আর test-কেও। অনেক দল একটি অভিন্ন আকার নেয়, যেমন RFC 9457-এর problem details; Full-Stack কোর্সের পর্ব ৩৩-এ এর বিস্তারিত।

Content negotiation — কে কোন ভাষায় কথা বলবে

Client দুটি header দিয়ে ধরন জানায়: Content-Type বলে “আমি যে body পাঠালাম তা এই ধরনের”, আর Accept বলে “আমি এই ধরনের উত্তর বুঝি”। Server উত্তরে নিজের Content-Type দেয়। মান-নথির হিসাবে, server যে ধরনের body পড়তে পারে না তা পেলে 415, আর client-এর চাওয়া ধরনে উত্তর দিতে না পারলে 406. বাজারঘরে JSON-এর বদলে plain text পাঠালে কী হয়, সত্যিকারের run:

$ curl -s -X POST http://127.0.0.1:8782/api/auth/login -H "Content-Type: text/plain" \
    -d '{"email":"mitu@bazarghar.test","password":"mitu1234"}'
{"detail":[{"type":"model_attributes_type","loc":["body"],"msg":"Input should be a valid
dictionary or object to extract fields from","input":"{\"email\":\"mitu@bazarghar.test\",
\"password\":\"mitu1234\"}"}]}

$ curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:8782/api/auth/login \
    -d 'email=mitu@bazarghar.test&password=mitu1234'
422

দুবারই 422, 415 নয়। App-এর framework (FastAPI) body-কে JSON object হিসেবে পড়তে না পেরে একে “মান অচল” ধরেছে। দ্বিতীয় run-এ curl-এর -d নিজে থেকে application/x-www-form-urlencoded পাঠায়, যা HTML form-এর ধরন। Tester প্রথমে নথি দেখবেন: OpenAPI-তে 415 লেখা থাকলে এটি bug, না থাকলে নথি আর আচরণের ফাঁক, যা প্রশ্ন হিসেবে তুলবেন। এটি test oracle-এর প্রশ্ন: “ঠিক” কী, তা কোডের আচরণ নয়, চুক্তি ঠিক করে।

৬ · পরিচয় আর অনুমতি — cookie, bearer token, 401/403/404 আর CORS

HTTP নিজে কাউকে মনে রাখে না; প্রতিটি request আলাদা। তাই “আমি মিতু” কথাটি প্রতিবার পাঠাতে হয়। বাজারঘর দুই পথই মানে:

  • Bearer token: login-এর উত্তরে পাওয়া একটি এলোমেলো লেখা, যা প্রতিটি API request-এ Authorization: Bearer … header-এ যায়। “Bearer” মানে বাহক: যার হাতে টোকেন, তাকেই মালিক ধরা হয়, ঠিক বাসের টিকিটের মতো। তাই token কখনো bug report, screenshot বা log-এ পুরো দেবেন না।
  • Cookie: HTML login-এর পরে server bg_session নামের cookie বসায়, যা HttpOnly (পাতার JavaScript পড়তে পারে না) আর SameSite=Lax. Browser প্রতিটি request-এ নিজেই cookie পাঠায়। একই token cookie-তে দিলে API-ও মানে; সত্যিকারের run-এ curl -H "Cookie: bg_session=…" /api/me দিল 200 OK.

বড় পার্থক্য: cookie browser নিজে পাঠায়, তাই অন্য সাইট থেকে আসা request-এও যেতে পারে (CSRF ঝুঁকি); bearer token কোড পাঠায়। নিরাপত্তা-বিচার সাইবার নিরাপত্তা কোর্সের পর্ব ৪১-এ। এখানে পরিচয়-সম্পর্কিত চারটি সত্যিকারের উত্তর (header-এর কিছু লাইন বাদ):

$ curl -i http://127.0.0.1:8782/api/orders                       # no token
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer
{"detail":{"code":"not_authenticated","message":"লগইন প্রয়োজন"}}

$ curl -i -X POST …/api/auth/login -d '{"email":"mitu@bazarghar.test","password":"wrong"}' …
HTTP/1.1 401 Unauthorized
{"detail":{"code":"invalid_credentials","message":"ইমেইল বা পাসওয়ার্ড ভুল"}}

$ curl -i …/api/orders/5 -H "Authorization: Bearer …(mitu)"      # rafi's order
HTTP/1.1 404 Not Found
{"detail":{"code":"order_not_found","message":"অর্ডারটি পাওয়া যায়নি"}}

$ curl -i -X POST …/api/products/3/reviews -H "Authorization: Bearer …(sumi)" …
HTTP/1.1 403 Forbidden
{"detail":{"code":"not_eligible","message":"শুধু পৌঁছে যাওয়া (delivered) অর্ডারের পণ্যের রিভিউ দেওয়া যায়"}}

দ্বিতীয় উত্তরটি খেয়াল করুন: ভুল password-এ বার্তা “ইমেইল বা পাসওয়ার্ড ভুল”, কোনটি ভুল তা বলে না। “এই ইমেইলে কোনো account নেই” বললে কেউ অন্যের ইমেইল আছে কি না যাচাই করতে পারত। তৃতীয়টি §৩-এর সিদ্ধান্ত: অন্যের অর্ডারে 404. চতুর্থটিতে সুমি লগইন করা আর পণ্যটিও আছে, কিন্তু তাঁর তেলের অর্ডার এখনও delivered নয়, তাই 403. পরিচয়-সম্পর্কিত test-এর জন্য সবসময় অন্তত দুটি account লাগে: একজনের resource আরেকজন ছুঁতে পারে কি না, এটিই BOLA ধরনের দুর্বলতার test, যা সাইবার নিরাপত্তা কোর্সের পর্ব ৩৮-এ বিস্তারিত।

CORS এক অনুচ্ছেদে: Browser-এর same-origin policy অনুযায়ী এক সাইটের পাতার JavaScript অন্য সাইটের API-র উত্তর পড়তে পারে না, যদি না সেই API Access-Control-Allow-Origin header দিয়ে অনুমতি দেয়। কিছু request-এর আগে browser একটি OPTIONS “preflight” পাঠিয়ে অনুমতি চায়। বাজারঘর কোনো CORS header পাঠায় না (সত্যিকারের run-এ Origin: https://shop.example দিয়ে চাইলে উত্তরে অনুমতির header নেই, আর OPTIONS-এ 405). এর মানে অন্য সাইটের পাতা এই API পড়তে পারবে না, যা এখানে ঠিক। Tester-এর দুটি সতর্কতা: CORS শুধু browser মানে, curl বা Postman মানে না, তাই “curl-এ চলে, browser-এ চলে না” প্রায়ই CORS; আর CORS নিরাপত্তার দেয়াল নয়, শুধু browser-এর পড়ার নিয়ম। বিস্তারিত সাইবার নিরাপত্তা কোর্সের পর্ব ৩৬-এ।

৭ · Idempotency key — timeout-এর পরে নিরাপদ retry

এবার এই পর্বের সবচেয়ে দামি test. মিতু ৯৬১ টাকার অর্ডারের দাম mobile wallet-এ দিলেন। Wallet টাকা কেটেছে, কিন্তু উত্তর ফেরার আগেই সংযোগ সময় পার করেছে, তাই app পেয়েছে timeout আর মিতু দেখছেন 504. মিতুর প্রশ্ন: টাকা কি কেটেছে? আবার চাপব? এখানে সমস্যার মূল: network-এ পাঠানো একটি বার্তা পৌঁছেছে কি না, পাঠানো পক্ষ সবসময় নিশ্চিত হতে পারে না। নিরাপদ পথ হলো এমনভাবে retry করা, যাতে দুবার পৌঁছালেও কাজ একবারই হয়।

উপায় হলো Idempotency-Key header: client প্রতিটি নতুন কাজের জন্য একটি অনন্য key বানায়, আর একই কাজের প্রতিটি retry-তে সেই key-ই পাঠায়। Server key-টি মনে রাখে: আগে দেখা key এলে কাজটি আবার না করে আগের ফল ফেরত দেয়। এই header-এর একটি মান-নথি IETF-এ খসড়া অবস্থায় আলোচিত হচ্ছে; ধারণাটি অবশ্য বহু বছর ধরে payment API-তে প্রচলিত। বাজারঘরের নকল wallet-এ timeout_once mode আছে: প্রথম লেনদেনে টাকা কাটে কিন্তু timeout দেখায়, পরেরগুলো স্বাভাবিক। নিচের stepper সত্যিকারের দুটি run ধরে এগোয়: প্রথমে সঠিক app, তারপর seeded bug double_charge_no_idempotency চালু করে।

1PUT wallet timeout_once2POST /orders/8/pay (K)3POST /orders/8/pay (K)4POST /orders/8/pay (K)5GET /api/test/wallet
অবস্থা
build
শেষ উত্তর
অর্ডার ৮
wallet-এ কাটা
  1. প্রথম চেষ্টা। Test-mode endpoint দিয়ে wallet-কে timeout_once-এ রাখা হলো, তারপর key pay-8-a1-সহ (code-এ K) পেমেন্ট। Wallet ৯৬১ টাকা কেটে ledger-এ লিখেছে, কিন্তু app timeout দেখেছে: উত্তর 504, অর্ডার এখনও placed. Client-এর চোখে টাকা কাটেনি বলে মনে হয়, অথচ কেটেছে।
  2. সিদ্ধান্ত। Client জানে না কী হয়েছে। §৩-এর helper-এর হিসাব: POST, 504, key আছে, তাই retry নিরাপদ। শর্ত একটাই, একই key. নতুন key বানালে server একে নতুন কাজ ধরবে।
  3. দ্বিতীয় চেষ্টা। একই key. Wallet-এর ledger reference হিসেবে key-টি রাখে, তাই আগের লেনদেন চিনে নতুন করে কাটেনি। App এবার সফল উত্তর পেল: 200, অর্ডার paid, ledger-এ এখনও একটিই লেনদেন।
  4. তৃতীয় চেষ্টা। ধরুন মিতুর app একই key-তে আরেকবার পাঠাল। Server জমানো উত্তরটিই ফেরত দিল, 200 আর সাথে Idempotent-Replayed: true header. শেষে ledger দেখায়: অর্ডার ৮-এর জন্য ঠিক ১টি লেনদেন। এটিই test-এর আসল assertion, status code নয়।
  5. Bug চালু, প্রথম চেষ্টা। App নতুন করে seed করে BAZARGHAR_BUGS=double_charge_no_idempotency দিয়ে চালানো হলো; এই build key উপেক্ষা করে। প্রথম চেষ্টা আগের মতোই: 504, টাকা কাটা ১ বার। এখন পর্যন্ত কোনো পার্থক্য চোখে পড়ে না।
  6. Bug চালু, retry. দ্বিতীয় চেষ্টায় wallet নতুন লেনদেন ভেবে আবার কেটেছে: 200, কিন্তু ledger-এ ৯৬১ টাকা দুবার। তৃতীয় চেষ্টায় 409, কারণ অর্ডার ইতিমধ্যে paid. শুধু status code দেখা একটি test এই run-কে প্রায় স্বাভাবিক বলত; ledger গোনা test bug-টি ধরল।

Stepper-এর সংখ্যাগুলো এই script-এর সত্যিকারের দুটি run থেকে (curl 8.13.0; script আর পুরো সংস্করণ নিজের lab-এ, path ছোট করা)। প্রথমে bug চালু অবস্থায়, তারপর app সঠিক build-এ আবার চালিয়ে:

$ BAZARGHAR_BUGS=double_charge_no_idempotency uv run bazarghar --port 8782 --test-mode --reset
$ sh retry_demo.sh
create order -> 201
pay try 1 -> 504
pay try 2 -> 200
pay try 3 -> 409
charges for order 8: 2 [961, 961]

$ uv run bazarghar --port 8782 --test-mode --reset          # correct build
$ sh retry_demo.sh
create order -> 201
pay try 1 -> 504
pay try 2 -> 200
pay try 3 -> 200
charges for order 8: 1 [961]

Script-টি curl-এর -w "%{http_code}" দিয়ে শুধু status ছাপে, আর শেষে test-mode-এর GET /api/test/wallet থেকে অর্ডার ৮-এর লেনদেন গোনে। App-এর নথি অনুযায়ী আরও দুটি negative test: একই key অন্য অর্ডারে দিলে 422 idempotency_key_reused, আর ১০০ অক্ষরের বেশি key-তে 422 invalid_idempotency_key. Key ছাড়া retry করলে সঠিক build-ও দুবার কাটে; §৮-এর HAR-এ দেখবেন। এই সুরক্ষা শুধু সেই client-এর জন্য, যে সব retry-তে একই key পাঠায়। বাজারঘরের HTML pay form প্রতিবার পাতা খুললে নতুন key বানায়, তাই timeout-এর পরে form থেকে আবার চাপলে সঠিক build-এও দুবার কাটে; এই সত্যিকারের defect ধরা পড়ে পর্ব ৩৭-এ।

৮ · হাতিয়ার — DevTools Network, curl আর HTTPie

তিনটি হাতিয়ার, তিন কাজের জন্য। Browser-এর DevTools-এর Network ট্যাব (F12 চেপে খুলুন) দেখায় পাতাটি আসলে কোন কোন request পাঠাল: method, URL, status, সময়, header আর body. Manual testing-এর সময় এটি খোলা রাখুন; সবুজ বার্তার নিচে হয়তো একটি 500 লুকিয়ে আছে। ডান-ক্লিকে “Copy as cURL” দিলে request-টি হুবহু curl command হয়ে যায়, যা bug report-এ পুনরুৎপাদনের ধাপ হিসেবে দারুণ (token মুছে দিয়ে)। পুরো session “Save all as HAR” দিয়ে একটি HAR ফাইলে রাখা যায়, যার ব্যবহার পর্ব ১৮-এ দেখেছেন।

DevTools Network

Browser যা করে তা দেখা: cookie, CORS, পাতার JavaScript-এর request, সময়ের হিসাব। পুনরুৎপাদনের জন্য Copy as cURL আর HAR.

দেখা

curl

প্রায় সব যন্ত্রে আছে (Windows ১০-এর ২০১৮ সালের সংস্করণ থেকে সাথেই আসে)। Script-এ, CI-তে, bug report-এ। -i header, -v পুরো আলাপ, -w নিজের মতো ফল।

পুনরুৎপাদন

HTTPie

মানুষের পড়ার জন্য বানানো command-line client: JSON নিজে বানায়, রং আর সাজানো output দেয়। হাতে-কলমে explore করতে সুবিধা।

খোঁজা

curl তৈরি করেন Daniel Stenberg, প্রথম প্রকাশ ১৯৯৮ সালে; licence curl license, যা MIT-ধাঁচের। HTTPie শুরু করেন Jakub Roztočil, ২০১২ সালের দিকে; licence BSD-3-Clause. HTTPie নিজের lab-এর uv venv-এ বসানো হয়েছে (uv add httpie, version 3.2.4). এর লেখার ধরন: key=value মানে JSON string, key:=value মানে JSON সংখ্যা বা true/false, key==value মানে query parameter, আর Name:value মানে header. সত্যিকারের run, --print=Hb দিয়ে পাঠানো header আর পাওয়া body (Accept-Encoding আর Connection লাইন বাদ):

$ http --pretty=format --print=Hb :8782/api/pricing/quote subtotal==2000 district==Dhaka plus==false
GET /api/pricing/quote?subtotal=2000&district=Dhaka&plus=false HTTP/1.1
Accept: */*
Host: localhost:8782
User-Agent: HTTPie/3.2.4

{
    "delivery": 0,
    "discount": 200,
    "district": "Dhaka",
    "plus": false,
    "subtotal": 2000,
    "total": 1800
}

$ http --pretty=format --print=hb :8782/api/pricing/quote subtotal==2000 district==Dhka
HTTP/1.1 422 Unprocessable Entity
content-type: application/json

{
    "detail": {
        "allowed": ["Dhaka", "Gazipur", "Narayanganj", "Chattogram", "Rajshahi", "Khulna",
                    "Sylhet", "Barishal", "Rangpur", "Mymensingh", "Cumilla", "Bogura"],
        "code": "invalid_district",
        "message": "জেলা সঠিক নয়"
    }
}

প্রথম run মডিউল ২-এর নিয়মটিই নিশ্চিত করে: ঢাকায় ২০০০ টাকায় ছাড় ২০০, আর delivery ফ্রি কারণ সীমা মাপা হয় ছাড়ের আগের দামে; মোট ১৮০০। :8782 লিখলে HTTPie নিজে localhost ধরে নেয়। দ্বিতীয় run-এ বানান ভুল “Dhka”: উত্তরে বৈধ জেলার তালিকা, যা tester-এর জন্য তৈরি equivalence partition-এর তালিকা (লম্বা array এখানে এক লাইনে সাজানো)। এমন একটি “pure” endpoint থাকায় দামের সব boundary value login ছাড়াই যাচাই করা যায়।

শেষে একটি HAR-ধাঁচের রেকর্ড পড়া। একটি ছোট Python script (stdlib urllib) app-এর সাথে একটি পুরো checkout চালিয়ে প্রতিটি request-এর method, URL, status আর সময় রেকর্ড করেছে, ঠিক যেমন DevTools করে। App চালানো ছিল slow_search bug-সহ, আর এই client টাকা দেওয়ার retry-তে কোনো key পাঠায় না। নিচের JavaScript block সেই রেকর্ডের দরকারি অংশ পড়ে সমস্যা খোঁজে:

// HAR-like log recorded from a real checkout run (bug switch slow_search on)
const har = {log: {entries: [
  {m: "GET",  url: "/api/products?q=oil", status: 200, time: 1506, h: []},
  {m: "POST", url: "/api/auth/login",     status: 200, time: 12, h: []},
  {m: "POST", url: "/api/cart/items",     status: 200, time: 11, h: ["Authorization"]},
  {m: "POST", url: "/api/cart/items",     status: 200, time: 11, h: ["Authorization"]},
  {m: "POST", url: "/api/orders",         status: 201, time: 13, h: ["Authorization"]},
  {m: "POST", url: "/api/orders/8/pay",   status: 504, time: 10, h: ["Authorization"]},
  {m: "POST", url: "/api/orders/8/pay",   status: 200, time: 10, h: ["Authorization"]},
  {m: "GET",  url: "/api/orders/8",       status: 200, time: 4,  h: ["Authorization"]},
]}};
const SLOW_MS = 1000, seen = new Map(), notes = [];
har.log.entries.forEach((e, i) => {
  const n = String(i + 1).padStart(2);
  console.log(`${n} ${e.m.padEnd(4)} ${e.url.padEnd(20)} ${e.status} ${String(e.time).padStart(5)} ms`);
  if (e.status >= 500) notes.push(`#${i + 1} server-side error ${e.status}`);
  if (e.time > SLOW_MS) notes.push(`#${i + 1} slow: ${e.time} ms > ${SLOW_MS} ms`);
  const unsafe = !["GET", "HEAD", "OPTIONS", "PUT", "DELETE"].includes(e.m);
  const key = `${e.m} ${e.url}`;
  if (unsafe && /\/pay$/.test(e.url) && seen.has(key) && !e.h.includes("Idempotency-Key"))
    notes.push(`#${i + 1} repeats #${seen.get(key)} (POST pay) with no Idempotency-Key: double charge risk`);
  if (!seen.has(key)) seen.set(key, i + 1);
});
console.log("\nfindings:");
notes.forEach((t) => console.log(" - " + t));

আসল আউটপুট (ব্রাউজারের JavaScript):

 1 GET  /api/products?q=oil  200  1506 ms
 2 POST /api/auth/login      200    12 ms
 3 POST /api/cart/items      200    11 ms
 4 POST /api/cart/items      200    11 ms
 5 POST /api/orders          201    13 ms
 6 POST /api/orders/8/pay    504    10 ms
 7 POST /api/orders/8/pay    200    10 ms
 8 GET  /api/orders/8        200     4 ms

findings:
 - #1 slow: 1506 ms > 1000 ms
 - #6 server-side error 504
 - #7 repeats #6 (POST pay) with no Idempotency-Key: double charge risk

তিনটি পর্যবেক্ষণ, তিনটিই সত্যিকারের run-এর। প্রথম, তেলের খোঁজে দেড় সেকেন্ড, যেখানে বাকি সব request ১৫ মিলিসেকেন্ডের কম: slow_search bug-টি status code-এ দেখা যায় না (200), শুধু সময়ে। দ্বিতীয়, একটি 504. তৃতীয় আর সবচেয়ে গুরুতর: একই POST দুবার, key ছাড়া। রেকর্ডিং script শেষে ledger দেখেছিল: charges for order 8: [961, 961]. এবার app সঠিক build-এ ছিল; ভুলটি client-এর, কারণ সে key পাঠায়নি। সংখ্যাগুলো একটি চলার সময় মাপা, তাই আপনার যন্ত্রে মিলিসেকেন্ড ভিন্ন হবে, কিন্তু অনুপাত একই থাকবে। পর্ব ৪০ (Flaky test — কারণ, খোঁজা, quarantine আর স্থায়ী সমাধান)-এ দেখবেন, সময়ের ওপর কড়া assertion কেন flaky হয়।

আরও গভীরে: HTTP-র মান-নথি তিন দশকে কয়েকবার নতুন করে লেখা হয়েছে: RFC 1945 (১৯৯৬, HTTP/1.0), RFC 2616 (১৯৯৯), RFC 7230-7235 (২০১৪), আর এখন RFC 9110-9112 (২০২২), যেখানে অর্থ (semantics) আর তারের ওপর রূপ (HTTP/1.1, HTTP/2, HTTP/3) আলাদা নথিতে। Tester-এর জন্য এর ফল: method আর status code-এর অর্থ HTTP/3-তেও একই, যদিও তারের ওপর বার্তা আর লেখা থাকে না, binary frame হয়ে যায়। বড় system-এ সামনে প্রায়ই একটি API gateway বা proxy বসে, যা নিজেই 401, 429, 502, 503 দিতে পারে; তখন “কে এই code দিল” প্রশ্নটিই debugging-এর প্রথম ধাপ।

পরীক্ষা ও ইন্টারভিউতে: বিশ্ববিদ্যালয়, চাকরি বা ইন্টারভিউর পরীক্ষায় এমন প্রশ্ন চেনা:

  • Safe আর idempotent method-এর পার্থক্য কী? উদাহরণ দিন। — Safe অবস্থা বদলায় না (GET); idempotent বারবার পাঠালেও অবস্থা একই (PUT, DELETE, আর সব safe method); POST দুটির কোনোটিই নয়।
  • 401 আর 403-এর পার্থক্য? — 401: পরিচয় নেই বা অচল, সাথে WWW-Authenticate; 403: পরিচয় জানা, কিন্তু অনুমতি নেই।
  • 400 বনাম 422? — 400: অনুরোধ পড়াই যায় না; 422: পড়া গেছে, কিন্তু মান নিয়ম ভাঙে। দল যেটিই নিক, পুরো API-তে একই রীতি।
  • Idempotency key কেন লাগে? — Timeout-এর পরে client জানে না কাজ হয়েছে কি না; একই key দিয়ে retry করলে server কাজটি দ্বিতীয়বার না করে আগের ফল দেয়।
  • Path আর query parameter কখন? — নির্দিষ্ট resource চিনতে path (/orders/8), খোঁজা, ছাঁকা আর পাতা ভাগে query (?q=tea&limit=2).

৯ · AI-এর যুগে API আর HTTP testing

AI assistant-কে “এই API-র test লিখে দাও” বললে কয়েকটি চেনা ভুল আসে। শুধু happy path: প্রতিটি endpoint-এ একটি 200, কোনো 401, 404 বা 409 নেই। Code-এর অনুমান: AI প্রায়ই “সাধারণ রীতি” থেকে 403 বা 400 লিখে দেয়, অথচ বাজারঘর নথিতে লেখা সিদ্ধান্তে 404 আর 422 দেয়; উল্টোটাও ঘটে, test app-এর বর্তমান উত্তর দেখে লেখা হয়। বানানো field আর option: order.total_amount (আসলে pricing.total), বা curl-এর অস্তিত্বহীন flag. Timeout-এর test-এ sleep(5). পেমেন্টের test-এ শুধু status code, ledger গোনা নেই, ফলে §৭-এর bug পাস করে যায়। আর চালানো ছাড়াই “সব test পাস” দাবি।

AI-কে চুক্তি আর সীমা স্পষ্ট করে দিন, আর প্রতিটি দাবির উৎস চান:

আমি বাজারঘর নামের একটি অনুশীলনী app-এর API test করছি, যা শুধু আমার যন্ত্রে 127.0.0.1:8782-এ চলে। নিচে এর OpenAPI নথির অংশ আর README-র error-এর নিয়ম দিলাম: [এখানে /api/orders/{id}/pay আর /api/orders/{id}/transition-এর অংশ] ১. প্রতিটি endpoint-এর জন্য একটি টেবিল দাও: পরিস্থিতি, পাঠানো request, প্রত্যাশিত status code, আর প্রত্যাশা নথির কোন লাইন থেকে এসেছে। নথিতে না থাকলে "নথিতে নেই" লেখো, অনুমান করবে না। ২. প্রতিটি negative test-এ একটিই ভুল রাখো: token ছাড়া, অন্যের অর্ডার, ভুল অবস্থা, ভুল type আলাদা আলাদা। ৩. পেমেন্টের retry test-এ শুধু status নয়, GET /api/test/wallet থেকে অর্ডারের লেনদেন গুনে assert করো। একই Idempotency-Key আর key ছাড়া, দুটি case দাও। ৪. curl command দিলে শুধু curl-এর official নথিতে আছে এমন option ব্যবহার করো; বাংলা query হলে --data-urlencode দাও। ৫. কোনো sleep নয়। আর test চালিয়েছ বলে দাবি করবে না; শুধু বলো কোন command চালালে কী দেখার আশা করি।

AI-এর দেওয়া API test হাতে পেলে — যাচাইয়ের চেকলিস্ট

ভাবনার প্রশ্ন

প্রতিটি প্রশ্ন নিয়ে নিজে কিছুক্ষণ ভাবুন, তারপর “→ উত্তর” চাপুন।

প্র ০১Roy Fielding-এর REST আর আজকের “REST API” কি একই জিনিস? একজন tester-এর কাছে এই পার্থক্যের কোনো মূল্য আছে কি?

Roy Fielding ২০০০ সালে University of California, Irvine-এ তাঁর PhD গবেষণাপত্রে REST (Representational State Transfer) বর্ণনা করেন। তিনি নিজে HTTP/1.1-এর মান-নথির অন্যতম লেখক ছিলেন, আর REST ছিল ওয়েব কেন সফলভাবে এত বড় হতে পারল, তার একটি স্থাপত্য-ব্যাখ্যা: client আর server আলাদা, প্রতিটি request স্বয়ংসম্পূর্ণ (stateless), উত্তর cache করা যায়, সবার জন্য একটি অভিন্ন interface, আর স্তরে স্তরে সাজানো system. অভিন্ন interface-এর একটি অংশ হলো hypermedia: উত্তরের ভেতরেই পরের সম্ভাব্য কাজের link থাকবে, যাতে client আগে থেকে সব URL না জেনেও চলতে পারে।

আজ যাকে সাধারণভাবে “REST API” বলা হয়, তার বেশিরভাগ আসলে “HTTP-র ওপর JSON”: resource-এর URL আর method আছে, কিন্তু hypermedia নেই, client-এর কোডে URL বাঁধা। Fielding নিজে ২০০৮ সালের একটি blog লেখায় এ নিয়ে অসন্তোষ জানিয়েছিলেন বলে পরিচিত। Leonard Richardson একটি ধাপের মডেল প্রস্তাব করেন, যা Martin Fowler ২০১০ সালে একটি লেখায় জনপ্রিয় করেন এবং যা Richardson maturity model নামে পরিচিত: শূন্য ধাপে একটি URL-এ সব কাজ, প্রথম ধাপে আলাদা resource, দ্বিতীয় ধাপে HTTP method আর status code-এর সঠিক ব্যবহার, তৃতীয় ধাপে hypermedia. বেশিরভাগ বাস্তব API দ্বিতীয় ধাপে থামে।

Tester-এর কাছে মূল্যটি তাত্ত্বিক বিশুদ্ধতায় নয়, প্রত্যাশায়। দ্বিতীয় ধাপের API-তে method আর status code অর্থ বহন করে, তাই এই পর্বের প্রতিটি test (GET-এর পরে অবস্থা না বদলানো, PUT-এর idempotency, 409-এর সঠিক ব্যবহার) প্রাসঙ্গিক। শূন্য ধাপের API-তে, যেখানে সব request POST /api আর সব উত্তর 200, ভুল খবরও body-র ভেতরে "ok": false হয়ে আসে; সেখানে status code-এর ওপর assertion অর্থহীন। বাজারঘরের allowed_actions field hypermedia-র একটি হালকা ছায়া, যা পর্ব ১০-এর state table-এর সাথে মেলানো যায়।

একটি বাস্তব পরামর্শ: “আমাদের API RESTful কি না” বিতর্কে না গিয়ে জিজ্ঞেস করুন, “আমাদের চুক্তি কী বলে?” Test সেই চুক্তির।

মূল উপলব্ধি: REST একটি স্থাপত্য-শৈলী, কোনো মান-নথি নয়; tester-এর কাজ API কোন রীতি মেনে চলার দাবি করে তা জেনে সেই দাবিকে test করা।

প্র ০২422 code-টি কোথা থেকে এল, আর কেন বিভিন্ন framework একই ভুলে 400, 415 বা 422 দেয়? Tester কীভাবে বিচার করবেন কোনটি “ঠিক”?

422 মূল HTTP-তে ছিল না। এটি আসে WebDAV-এর মান-নথি থেকে (প্রথমে RFC 2518, ১৯৯৯; পরে RFC 4918, ২০০৭), যেখানে এর নাম ছিল “Unprocessable Entity”: অনুরোধের গঠন আর ধরন ঠিক, কিন্তু ভেতরের নির্দেশ মানা যাচ্ছে না। বহু বছর এটি শুধু WebDAV-এর code হলেও API-র দুনিয়ায় validation ভুলের জন্য জনপ্রিয় হয়ে ওঠে, কারণ 400 খুব সাধারণ মনে হতো। ২০২২ সালের RFC 9110 একে HTTP-র মূল নথিতে নিয়ে আসে আর নাম দেয় “Unprocessable Content”. বাজারঘরের run-এ uvicorn এখনও পুরোনো নাম “Unprocessable Entity” ছাপে; নাম শুধু বর্ণনা, যন্ত্র পড়ে সংখ্যাটি, তাই test-এ নামের ওপর assertion লেখা অর্থহীন।

Framework-ভেদে পার্থক্যের কারণ ইতিহাস আর দর্শন। FastAPI শুরু থেকেই request-এর schema যাচাই ব্যর্থ হলে 422 দেয়, আর ভুল Content-Type-কেও প্রায়ই একই পথে পাঠায়, যেমনটি §৫-এর run-এ দেখা গেল। অন্য কিছু framework একই ক্ষেত্রে 400 দেয়, আর কিছু ভুল ধরনের body-তে 415. মান-নথি সব ক্ষেত্রে একটিমাত্র উত্তর বেঁধে দেয় না; কোন code “বেশি মানানসই”, তা নিয়ে অভিজ্ঞ লোকেরাও দ্বিমত করেন।

তাহলে tester কী করবেন? তিনটি ধাপ। প্রথম, চুক্তি খুঁজুন: OpenAPI, দলের API guideline, বা গ্রহণযোগ্যতার শর্ত। চুক্তিতে যা লেখা, সেটিই test oracle. দ্বিতীয়, ধারাবাহিকতা যাচাই করুন: একই ধরনের ভুলে পুরো API-তে একই code আর একই আকারের body আসছে কি না। একটি endpoint ভুল type-এ 400 আর আরেকটি 422 দিলে client-এর কোডে দুই রকম শাখা লাগে, যা নিজেই একটি ত্রুটি। তৃতীয়, চুক্তিতে ফাঁক পেলে সেটি bug হিসেবে নয়, প্রশ্ন হিসেবে তুলুন, প্রমাণসহ: “text/plain পাঠালে 422 আসে, নথিতে কিছু লেখা নেই; আমরা কি 415 চাই, না বর্তমান আচরণই নথিতে যোগ করব?” এই প্রশ্নের উত্তর যা-ই হোক, তারপর একটি test তা পাহারা দেবে।

Postel-এর বিখ্যাত নীতি “যা পাঠান তাতে কঠোর হোন, যা নেন তাতে উদার” (১৯৮০-র দশকের TCP নথি থেকে) এখানে প্রায়ই উল্লেখ হয়। কিন্তু অতি-উদার server ভুলকে চুপচাপ মেনে নেয়, আর সেই ভুলই পরে client-এর অভ্যাস হয়ে যায়; তাই বাজারঘরের "stars":"5" প্রত্যাখ্যান বেশি নিরাপদ।

মূল উপলব্ধি: “ঠিক” status code প্রায়ই মান-নথি নয়, দলের চুক্তি ঠিক করে; tester-এর কাজ চুক্তি, আচরণ আর ধারাবাহিকতা তিনটি মেলানো।

প্র ০৩অন্যের অর্ডারে 403 না দিয়ে 404 দেওয়া কি সত্য গোপন করা? API নিরাপত্তার কোন ইতিহাস এই সিদ্ধান্তের পেছনে, আর tester এটি কীভাবে যাচাই করবেন?

মান-নথি নিজেই এই পথ খোলা রেখেছে: RFC 9110-এ বলা আছে, server যদি একটি resource-এর অস্তিত্বই জানাতে না চায়, তাহলে 403-এর বদলে 404 দিতে পারে। কারণ 403 একটি তথ্য দেয়: “এই id-তে কিছু আছে।” একজন আক্রমণকারী id ১, ২, ৩... ধরে চেষ্টা করলে 403 আর 404-এর পার্থক্য থেকে জানতে পারেন কতগুলো অর্ডার আছে, দোকান দিনে কত বিক্রি করে, এমনকি নতুন অর্ডারের হার।

এর পেছনের বড় সমস্যাটির নাম IDOR (insecure direct object reference), যা OWASP-এর পুরোনো Top 10 তালিকায় আলাদা জায়গা পেয়েছিল। API-র যুগে OWASP API Security Top 10 প্রকাশ করে (প্রথম ২০১৯ সালে, হালনাগাদ ২০২৩ সালে), আর দুই সংস্করণেই প্রথম স্থানে ছিল Broken Object Level Authorization, সংক্ষেপে BOLA: server পরিচয় যাচাই করে, কিন্তু resource-টি এই ব্যক্তির কি না, তা যাচাই করতে ভুলে যায়। এটি প্রথম স্থানে থাকার কারণ এর সরলতা: কোনো জটিল কৌশল লাগে না, শুধু URL-এর একটি সংখ্যা বদলানো।

Tester-এর জন্য এর পরীক্ষা পদ্ধতিগত। অন্তত দুটি সাধারণ account আর একটি admin নিন। প্রতিটি endpoint-এ যেখানে path-এ একটি id আছে, ক-এর resource খ-এর token দিয়ে চান: GET, পরিবর্তন, মোছা, আর /pay বা /transition-এর মতো action. প্রত্যাশা: প্রতিটিতে 404 (বা নথিতে লেখা 403), আর পার্শ্বফল শূন্য, অর্থাৎ অবস্থা অপরিবর্তিত। তারপর তুলনা করুন: “আছে কিন্তু অন্যের” আর “একেবারে নেই” id-তে উত্তর হুবহু একই কি না, body-র বার্তাসহ, আর সময়েও বড় পার্থক্য নেই তো? বার্তায় ছোট একটি পার্থক্যও (“অর্ডার পাওয়া যায়নি” বনাম “অর্ডার নেই”) তথ্য ফাঁস করে। বাজারঘরে দুই ক্ষেত্রেই order_not_found.

সত্য গোপনের প্রশ্নে: মালিকের কাছে কিছুই গোপন নয়; গোপন থাকে শুধু অন্যের ব্যবসার তথ্য। খরচ একটাই: support-এর কাজে আসল কারণ জানতে server-এর log-এ তা লেখা থাকা উচিত, উত্তরে নয়।

মূল উপলব্ধি: Status code-ও একটি তথ্য-প্রবাহ; অনুমতির test-এ দুটি account দিয়ে উত্তর, body আর পার্শ্বফল তিনটিই মেলাতে হয়।

প্র ০৪“দুই সেনাপতির সমস্যা” কী, আর কেন এটি প্রমাণ করে যে timeout-এর পরে নিশ্চিতভাবে “একবার” কাজ করানো network দিয়ে সম্ভব নয়? Idempotency key এই সমস্যার কতটা সমাধান করে?

দুই সেনাপতির সমস্যা distributed computing-এর একটি পুরোনো চিন্তা-পরীক্ষা। এর একটি রূপ ১৯৭৫ সালে Akkoyunlu, Ekanadham আর Huber-এর একটি গবেষণাপত্রে আসে, আর “two generals” নামটি জনপ্রিয় হয় Jim Gray-এর ১৯৭৮ সালের লেখা থেকে। দুই পাহাড়ে দুই সেনাপতি, মাঝে শত্রুর উপত্যকা; একসাথে আক্রমণ করলেই জয়। বার্তাবাহক উপত্যকা পার হতে গিয়ে ধরা পড়তে পারে। ক বার্তা পাঠালেন, “ভোরে আক্রমণ।” খ পেলেন কি না, ক জানেন না, তাই খ-কে প্রাপ্তি জানাতে হবে; কিন্তু সেই প্রাপ্তি পৌঁছাল কি না, খ জানেন না। যত প্রাপ্তিই পাঠানো হোক, শেষ বার্তাটির অনিশ্চয়তা থেকেই যায়। প্রমাণ করা যায় যে অবিশ্বস্ত পথে সীমিত সংখ্যক বার্তায় দুই পক্ষের নিশ্চিত ঐকমত্য অসম্ভব।

মিতুর 504 ঠিক এই অবস্থা। App wallet-কে বলল “৯৬১ টাকা কাটো”, উত্তর এল না। তিনটি সম্ভাবনা: অনুরোধ পৌঁছায়নি, পৌঁছে কাজ হয়নি, বা কাজ হয়েছে কিন্তু উত্তর হারিয়েছে। App-এর পক্ষে কোনটি ঘটেছে, তা নিশ্চিত হওয়ার উপায় নেই। তাই দুটি পথ: retry না করা (টাকা হয়তো কাটেনি, অর্ডার ঝুলে থাকল; “সর্বোচ্চ একবার”), বা retry করা (টাকা দুবার কাটতে পারে; “অন্তত একবার”)। “ঠিক একবার” network-এর স্তরে অর্জন করা যায় না।

Idempotency key কৌশলটি এই সীমা মেনে নিয়ে কাজ করে: বার্তা “অন্তত একবার” পাঠানো হয় (যতক্ষণ না নিশ্চিত উত্তর আসে), আর গ্রহণকারী key দিয়ে duplicate চিনে কাজটি “সর্বোচ্চ একবার” করে। দুটি মিলে প্রভাব একবার, যদিও বার্তা একাধিকবার। শর্তগুলোও tester-এর test case: key client-এ একবার তৈরি হয়ে সব retry-তে একই থাকবে (§৭-এর ধাপ ২); server key আর ফল একসাথে, একটি transaction-এ জমাবে, নইলে মাঝপথে crash হলে key জমা হলো কিন্তু কাজ হলো না; একই key-তে ভিন্ন অনুরোধ এলে প্রত্যাখ্যান করবে (বাজারঘরের 422 idempotency_key_reused); আর key কতদিন মনে রাখা হবে, তার একটি নীতি থাকবে। এর বাইরে দুই পক্ষের হিসাব নিয়মিত মিলিয়ে দেখারও (reconciliation) দরকার আছে; ledger গোনা assertion তারই একটি ছোট রূপ।

মূল উপলব্ধি: Network-এ “ঠিক একবার” পাঠানো অসম্ভব, কিন্তু “অন্তত একবার পাঠানো + duplicate চেনা” দিয়ে প্রভাব একবার করা যায়; test-কে সেই প্রভাবই গুনতে হবে।

প্র ০৫UTF-8 কীভাবে এল, আর বাংলা লেখার জন্য একটি API-তে কোন কোন জায়গায় encoding-এর bug লুকিয়ে থাকতে পারে?

একসময় প্রতিটি ভাষা বা অঞ্চলের নিজস্ব encoding ছিল, আর বাংলার জন্য চলত একাধিক অ-মানক font-ভিত্তিক পদ্ধতি; একটিতে লেখা ফাইল আরেকটিতে খুললে অর্থহীন চিহ্ন। Unicode সব লিপির প্রতিটি অক্ষরকে একটি সংখ্যা (code point) দেয়; বাংলার জায়গা U+0980 থেকে U+09FF. কিন্তু সংখ্যাগুলো byte-এ কীভাবে লেখা হবে, তার জন্য encoding লাগে। ১৯৯২ সালে Ken Thompson আর Rob Pike UTF-8 নকশা করেন, যার একটি বড় সুবিধা: ইংরেজির ASCII অক্ষর এক byte-এই থাকে, ফলে পুরোনো সফটওয়্যার না ভেঙেই নতুন লিপি আসে। বাংলার প্রতিটি code point UTF-8-এ তিন byte. আজ ওয়েবের প্রায় সব পাতা UTF-8-এ, আর JSON-এর মান-নথি (RFC 8259, ২০১৭) system-এর বাইরে আদান-প্রদানে UTF-8 বাধ্যতামূলক করেছে।

তবুও bug আসে, কারণ পথে অনেক হাত বদল হয়। একটি বাংলা রিভিউ ব্রাউজার থেকে database-এ যেতে কয়েকটি জায়গা পার হয়, আর প্রতিটি জায়গা একটি test case: (১) URL: কাঁচা বাংলা পাঠালে এই পর্বের run-এ 400; client-কে percent-encode করতে হবে। (২) Request body: Content-Length byte-এ, অক্ষরে নয় (৮৩ বনাম ২৪)। (৩) Header: HTTP header-এ বাংলা সরাসরি লেখা যায় না; ফাইলের নাম বা বার্তা header-এ গেলে আলাদা encoding লাগে। (৪) Database আর তার collation: পুরোনো কিছু database-এ ভুল character set থাকলে লেখা প্রশ্নবোধক চিহ্ন হয়ে যায়। (৫) দৈর্ঘ্যের নিয়ম: রিভিউর ১০–৫০০ অক্ষর code point-এ মাপা, UTF-16 unit বা byte-এ নয়; app-এর review_utf16_length seeded bug ঠিক এই ভুল করে, যা পর্ব ১৫-১৮-এর রিভিউ feature-এ দেখেছেন। (৬) খোঁজা: বাংলায় একই দেখতে লেখা ভিন্ন code point-এর ক্রমে লেখা যায় (যেমন “য়” একটি অক্ষর হিসেবে, বা য-এর সাথে নুকতা যোগ করে), তাই “ঠিক মিল” খোঁজা ব্যর্থ হতে পারে, যদি না normalization করা হয়। বাজারঘরের খোঁজে এই ভুলটি সত্যিই ধরা পড়ে পর্ব ৫৬-এ।

Tester-এর জন্য একটি ব্যবহারিক নিয়ম: প্রতিটি text field-এর test data-য় অন্তত একটি বাংলা লেখা, একটি যুক্তাক্ষর (“ক্ষ”, “ন্ত”), একটি emoji আর একটি বাংলা অঙ্ক রাখুন, আর লেখাটি পুরো পথ ঘুরে ফেরত এলে byte ধরে মিলিয়ে দেখুন; ভুল প্রায়ই অন্য app বা export-এ প্রকাশ পায়।

মূল উপলব্ধি: UTF-8 সমস্যার সমাধান দিয়েছে, কিন্তু প্রতিটি হাত বদলের জায়গা নতুন করে ভুল করতে পারে; বাংলা test data দিয়ে পুরো যাত্রাপথ যাচাই করুন।

অনুশীলন

কাগজ-কলমে করুন, তারপর উত্তর মিলিয়ে নিন। উত্তরের সব code বাজারঘরের app-এ সত্যিকারের run দিয়ে মেলানো।

  1. Spec থেকে test (test design): বাজারঘরের নিয়ম: PUT /api/cart/items/{product_id}, body {"qty": n}. লগইন লাগবে; পণ্যটি cart-এ থাকতে হবে; qty একটি JSON পূর্ণসংখ্যা, ১ থেকে ১০, আর স্টকের বেশি নয়। গুঁড়া দুধের (id 11) স্টক ৩, আর সেটি মিতুর cart-এ ১টি আছে। এই নিয়ম থেকে অন্তত আটটি test case লিখুন: request আর প্রত্যাশিত status code. প্রতিটিতে একটিই ভুল রাখুন।
    CaseRequestপ্রত্যাশা
    বৈধ, নিচের সীমা/11 {"qty":1}200, qty 1
    বৈধ, স্টকের সীমা/11 {"qty":3}200, qty 3; আবার পাঠালেও 3
    স্টকের এক বেশি/11 {"qty":4}409 insufficient_stock, available: 3
    নিচের সীমার এক কম/11 {"qty":0}422, loc body.qty
    ওপরের সীমার এক বেশিডিম (স্টক ৪৫) {"qty":11}422
    ওপরের সীমাডিম {"qty":10}200
    ভুল type{"qty":"2"}, 2.5, nullতিনটিই 422 (আলাদা test)
    Cart-এ নেই/2 {"qty":1}404 not_in_cart
    লগইন নেইtoken ছাড়া /11401

    দুটি পর্যবেক্ষণ, যা run থেকে এসেছে। প্রথম, দুধে {"qty":10} দিলে 422 নয়, 409 আসে: ১০ বৈধ সীমার ভেতরে, কিন্তু স্টক ৩. তাই ওপরের সীমা ১০ যাচাই করতে এমন পণ্য লাগে যার স্টক ১০-এর বেশি (ডিম)। এটি §৩-এর “একবারে একটি ভুল” নিয়মের উদাহরণ। দ্বিতীয়, PUT idempotent: {"qty":3} দুবার পাঠালে qty ৩-ই থাকে, ৬ নয়; এটিও একটি test.

  2. আউটপুট অনুমান করুন (read the result): বাজারঘর BAZARGHAR_BUGS=double_charge_no_idempotency দিয়ে চালানো। মিতু ৯৬১ টাকার অর্ডার ৮ করলেন, wallet timeout_once mode-এ। তারপর একই Idempotency-Key: pay-8-a1-সহ POST /api/orders/8/pay তিনবার পাঠানো হলো। তিনটি status code কী হবে, আর wallet-এর ledger-এ অর্ডার ৮-এর কয়টি লেনদেন থাকবে? সঠিক build-এ উত্তর কী বদলাবে?

    Bug-ওয়ালা build: 504, 200, 409; ledger-এ ২টি লেনদেন (৯৬১, ৯৬১)। প্রথমটিতে টাকা কেটেছে কিন্তু timeout; দ্বিতীয়টিতে key উপেক্ষা করে আবার কেটেছে আর অর্ডার paid; তৃতীয়টিতে অর্ডার ইতিমধ্যে paid, তাই state machine-এর 409 invalid_transition. সঠিক build: 504, 200, 200 (শেষটিতে Idempotent-Replayed: true), ledger-এ ১টি. দুই run-ই §৭-এ সত্যিকারের। শিক্ষা: bug-ওয়ালা build-এর প্রথম দুটি code সঠিক build-এর সাথে হুবহু এক; শুধু status code দেখা test কিছুই ধরত না। তৃতীয় code-এর পার্থক্য চোখে পড়ার মতো, কিন্তু বাস্তবে তৃতীয় চেষ্টা প্রায়ই হয়ই না। নির্ভরযোগ্য assertion হলো ledger-এ লেনদেন গোনা।

  3. Bug report-এর ভুল খুঁজুন (find the bug): একজন নতুন tester লিখলেন:
    শিরোনাম: API কাজ করে না
    ধাপ: চাল খুঁজলাম, error দিল।
    curl "http://staging/api/products?q=চাল" -H "Authorization: Bearer 7Hq2…(পুরো token)"
    ফল: 400. প্রত্যাশা: 404 (চাল পাওয়া যায়নি দেখানো উচিত)
    গুরুত্ব: Critical
    এই report-এ অন্তত পাঁচটি সমস্যা খুঁজুন। এটি আদৌ app-এর bug কি?

    (১) শিরোনাম অস্পষ্ট: কোন API, কী ব্যর্থ? ভালো: “বাংলা শব্দে product search 400 দেয় যখন URL percent-encode করা হয় না”। (২) Token ফাঁস: পুরো bearer token report-এ দেওয়া নিরাপত্তার ভুল; … দিয়ে লুকান, আর এই endpoint-এ token লাগেই না, তাই অপ্রয়োজনীয়ও। (৩) ভুল প্রত্যাশা: খোঁজে কিছু না মিললেও 404 নয়, 200 আর খালি তালিকা প্রত্যাশিত (§৫); তা ছাড়া “চাল” পণ্য আছে। (৪) আসল কারণ বোঝা হয়নি: curl কাঁচা বাংলা byte পাঠিয়েছে, আর server-এর HTTP parser একে অচল request বলেছে। --data-urlencode "q=চাল" দিলে 200 আর চালের পণ্য আসে। (৫) পরিবেশ আর প্রমাণ নেই: curl-এর version, পুরো response (body-তে “Invalid HTTP request received.”), সময়, build. (৬) গুরুত্ব বাড়ানো: ব্রাউজার নিজে encode করে, তাই ব্যবহারকারীর ওপর প্রভাব নেই বললেই চলে; Critical নয়। সিদ্ধান্ত: app-এর bug নয়, test client-এর ভুল; তবে error-টি JSON নয় কেন, সেই প্রশ্ন তোলা যায়।

  4. একটি সফল উত্তর পড়া (ভেবে দেখুন): মিতুর নতুন অর্ডারের সত্যিকারের উত্তর (কিছু field বাদ): HTTP/1.1 201 Created, content-type: application/json, body {"id":8,"status":"placed","phone":"01712345678","pricing":{"subtotal":1001,"discount":100,"delivery":60,"total":961},"paid":false,"payment":null,"allowed_actions":["pay","cancel"],"created_at":"2026-11-16T17:27:35+06:00"}. পাঠানো phone ছিল " 01712345678 " (দুই পাশে ফাঁকা), জেলা Dhaka. একজন tester হিসেবে এই সফল উত্তরে কমপক্ষে পাঁচটি জিনিস যাচাই করুন, আর একটি প্রশ্ন লিখুন যা দলকে জিজ্ঞেস করবেন।

    যাচাই: (১) 201, 200 নয়, কারণ নতুন resource. (২) দামের নিয়ম: ১০০১-এ ছাড় ১০০ (১০% ভগ্নাংশ বাদ), ঢাকায় ২০০০-এর কম তাই delivery ৬০, মোট ১০০১ − ১০০ + ৬০ = ৯৬১; সব মান সংখ্যা, string নয়। (৩) Phone-এর দুই পাশের ফাঁকা কেটে রাখা হয়েছে, যা পর্ব ১৪-এর phone নিয়ম। (৪) "payment": null আর "paid": false পরস্পরের সাথে মেলে; টাকা দেওয়ার পরে দুটিই বদলাবে। (৫) allowed_actions ["pay","cancel"], যা পর্ব ১০-এর state table-এ placed অবস্থার বৈধ কাজ। (৬) created_at-এ +06:00, time zone আছে। প্রশ্ন: 201-এর সাথে Location: /api/orders/8 header নেই; client-কে body থেকে id পড়ে URL বানাতে হয়। নথিতে কি এটি ইচ্ছাকৃত? এটি bug নয়, চুক্তির প্রশ্ন।

নিজেকে যাচাই করুন

ভুল হলে কারণসহ ব্যাখ্যা পাবেন, আবার চেষ্টাও করতে পারবেন।

ক্রমIdempotency-Key দিয়ে একটি পেমেন্ট নিরাপদে retry করার ধাপগুলো সঠিক ক্রমে সাজান (▲▼ চেপে সরান)

  1. Client নতুন পেমেন্টের জন্য একটি অনন্য key তৈরি করে
  2. Key-সহ POST পাঠানো হয়, আর server key দেখে কাজ শুরু করে
  3. উত্তর আসে না বা timeout-এর error আসে
  4. Client একই key দিয়ে একই অনুরোধ আবার পাঠায়
  5. Server key চিনে কাজটি দ্বিতীয়বার না করে আগের ফল ফেরত দেয়

কোন HTTP method idempotent, কিন্তু safe নয়?

  • GET
  • POST
  • PUT
  • HEAD

একটি API-তে token ছাড়া GET /api/orders পাঠালে সবচেয়ে মানানসই উত্তর কোনটি?

  • 403 Forbidden
  • 401 Unauthorized, সাথে WWW-Authenticate header
  • 400 Bad Request
  • 200 OK, খালি তালিকাসহ

একটি request-এর body {"stars":5,"text":"ডাল খুব ভালো, আবার কিনব।"}, যেখানে লেখাটি ২৪ অক্ষরের আর পুরো JSON ৪৫ অক্ষরের। Content-Length কেন 83?

  • Header-এর byte-ও Content-Length-এ যোগ হয়
  • JSON-এর ভেতরে লুকানো ফাঁকা স্থান আছে
  • Body গোপন করার জন্য encrypt করা হয়েছে
  • Content-Length byte গোনে, আর UTF-8-এ প্রতিটি বাংলা অক্ষর ৩ byte

একটি mobile wallet পেমেন্টের POST request-এ 504 Gateway Timeout এল। Client-এর সবচেয়ে নিরাপদ পরের কাজ কোনটি?

  • আগের একই Idempotency-Key দিয়ে একই অনুরোধ আবার পাঠানো
  • নতুন একটি Idempotency-Key দিয়ে আবার পাঠানো
  • Key ছাড়াই দ্রুত আবার পাঠানো
  • ব্যবহারকারীকে জানানো যে টাকা কাটেনি, আবার অর্ডার করুন

একটি দোকানের API-তে GET /api/products?q=oil&limit=2 আর GET /api/products/3. এই দুটি সম্পর্কে কোন কথাটি ঠিক?

  • প্রথমটি অবস্থা বদলায়, দ্বিতীয়টি বদলায় না
  • দুটিতেই কিছু না মিললে 404 প্রত্যাশিত
  • প্রথমটিতে query তালিকা ছাঁকে, দ্বিতীয়টিতে path একটি নির্দিষ্ট resource চেনায়
  • প্রথমটির q আর limit request body-তে যায়

API নথিতে price একটি integer, কিন্তু response-এ এল "price":"230". পর্দায় দাম ঠিক “২৩০” দেখাচ্ছে। Tester-এর সবচেয়ে ভালো মূল্যায়ন কোনটি?

  • পর্দায় ঠিক দেখাচ্ছে, তাই bug নয়
  • চুক্তি ভাঙা একটি type bug, যা হিসাব করা অন্য client-কে ভুল ফল দেবে
  • একটি encoding সমস্যা, UTF-8 ঠিক করলেই সমাধান
  • Status code 200 হলে body-র type যাচাইয়ের দরকার নেই

একটি API curl দিয়ে ঠিকঠাক উত্তর দেয়, কিন্তু অন্য একটি domain-এর web পাতার JavaScript থেকে ডাকলে browser-এর console-এ error আসে আর উত্তর পড়া যায় না। সবচেয়ে সম্ভাব্য কারণ কোনটি?

  • Server বন্ধ হয়ে গেছে
  • Endpoint-এ ভুল HTTP method
  • Response-এর JSON ভাঙা
  • Server CORS-এর অনুমতির header পাঠাচ্ছে না, আর browser same-origin নিয়মে উত্তর আটকাচ্ছে

শব্দকোষ

লেখার মধ্যে ডটেড দাগ দেওয়া শব্দে মাউস রাখুন বা চাপুন, অর্থ দেখাবে। এই পর্বের সব নতুন শব্দ এখানে একসাথে:

মনে রাখুন

  1. বার্তার চার অংশ: request line বা status line, header, ফাঁকা লাইন, body. Tester চারটিই পড়েন; curl -v আর DevTools দুটিই দেখায়।
  2. Method একটি প্রতিশ্রুতি: GET safe, PUT আর DELETE idempotent, POST কোনোটিই নয়। প্রতিটি প্রতিশ্রুতি একটি test, আর ভুল method-এ 405 ও Allow.
  3. Status code একটি সিদ্ধান্ত: 401 পরিচয়, 403/404 অনুমতি, 409 অবস্থা, 422 মান; যেকোনো 500 bug. Negative test-এ একবারে একটি ভুল, আর “ঠিক” code ঠিক করে চুক্তি।
  4. JSON-এর নীরব bug: string-এ সংখ্যা, null বনাম শূন্য, বাংলা লেখার encoding (URL-এ percent-encoding, length byte-এ), time zone ছাড়া সময়।
  5. Retry-র নিয়ম: 4xx-এ retry নয়; POST-এর timeout-এ শুধু একই Idempotency-Key দিয়ে; আর পেমেন্টের test status নয়, ledger-এর লেনদেন গোনে।

পরের পর্বে: এই পর্বের হাতে চালানো request-গুলো একটি সাজানো collection-এ: environment variable, login token থেকে অর্ডারে chaining, CSV দিয়ে coupon-এর data-driven run, আর CI-তে Newman. পর্ব ৩০ (Postman আর Newman দিয়ে API testing).

আরও পড়ুন · ABCL TECH-এ আপনার পরবর্তী পদক্ষেপ

এই পর্বটি শেয়ার করুন:
এই পর্বে ভুল পেয়েছেন? জানান