REST API নকশার ভালো চর্চা: URL, status code ও error

API হলো আপনার server ও তা ব্যবহার করা client-দের মধ্যে চুক্তি। অন্যরা এর ওপর নির্ভর করলে বদলানো ব্যয়বহুল। পরিষ্কার নকশায় সময় দিলে বছরের পর বছর লাভ হয়।

১. Action নয়, resource ভাবুন

Resource হলো noun: user, order, product। URL-এ বহুবচন noun ব্যবহার করুন এবং HTTP method-কে verb হতে দিন।

কাজ	Request
Order-এর তালিকা	GET /orders
একটি order আনা	GET /orders/42
Order বানানো	POST /orders
Order প্রতিস্থাপন	PUT /orders/42
Order-এর অংশ হালনাগাদ	PATCH /orders/42
Order মোছা	DELETE /orders/42
Order-এর item-এর তালিকা	GET /orders/42/items

/getOrder বা /createUser-এর মতো URL-এ verb এড়ান। CRUD-তে না মেলা কাজে পরিষ্কার sub-resource বা action path ব্যবহার করুন, যেমন POST /orders/42/cancel।

URL ছোট হাতের, সামঞ্জস্যপূর্ণ এবং খুব গভীরভাবে নেস্টেড নয় রাখুন।

২. Method সঠিকভাবে ব্যবহার করুন

• GET পড়ে এবং data বদলাবে না। এটি নিরাপদ ও idempotent।
• POST তৈরি করে বা প্রক্রিয়া চালু করে। ডিফল্টে idempotent নয়।
• PUT প্রতিস্থাপন, PATCH আংশিক হালনাগাদ, DELETE মোছে। PUT ও DELETE idempotent।

৩. সঠিক status code ফেরত দিন

পরিস্থিতি	Code
body-সহ সফল	200 OK
তৈরি হয়েছে	201 Created (Location header-সহ)
সফল, body নেই	204 No Content
খারাপ ইনপুট	400 Bad Request, বা যাচাই error-এ 422
লগইন করা নেই	401 Unauthorized
লগইন আছে কিন্তু অনুমতি নেই	403 Forbidden
পাওয়া যায়নি	404 Not Found
দ্বন্দ্ব (যেমন ডুপ্লিকেট)	409 Conflict
অতিরিক্ত request	429 Too Many Requests (Retry-After-সহ)
Server ত্রুটি	500, 502, 503

Body-তে error লুকিয়ে কখনো 200 ফেরত দেবেন না।

৪. সামঞ্জস্যপূর্ণ error ফরম্যাট

Client সামলাতে পারে এমন অনুমানযোগ্য কাঠামো দিন:

{
  "error": {
    "code": "validation_failed",
    "message": "Email is not valid.",
    "details": [{ "field": "email", "issue": "invalid_format" }],
    "requestId": "a1b2c3"
  }
}

সহায়ক হোন কিন্তু ভেতরের তথ্য ফাঁস করবেন না: stack trace, SQL বা server path নয়। সেগুলো request ID-সহ server-এ log করুন।

৫. Pagination, filtering ও sorting

সীমাহীন তালিকা কখনো ফেরত দেবেন না।

• Pagination: ?limit=20&offset=40 সরল। Cursor-ভিত্তিক (?limit=20&after=abc) বড় বা বদলানো data-র জন্য বেশি স্থিতিশীল ও দ্রুত।
• Filtering: ?status=paid&created_after=2026-01-01।
• Sorting: ?sort=-created_at।
• সর্বোচ্চ পেজ আকার ঠিক করুন।
• উত্তরে paging তথ্য (পরের cursor বা মোট) ফেরত দিন।

৬. API-র version দিন

বদলের পরিকল্পনা করুন।

• URL-এ (/v1/orders) বা header-এ সংস্করণ রাখুন।
• নতুন ঐচ্ছিক field যোগ সাধারণত নিরাপদ। Field সরানো বা নাম বদল, বা অর্থ বদল ভাঙনকারী পরিবর্তন এবং নতুন সংস্করণ চায়।
• তারিখসহ deprecation ঘোষণা করুন এবং client-কে সরার সময় দিন।

৭. নিরাপদ retry-র জন্য idempotency

Network ব্যর্থ হয় এবং client retry করে। পার্শ্বপ্রতিক্রিয়াসহ POST request-এ (পেমেন্ট, order) Idempotency-Key header নিন। একই key আবার এলে ডুপ্লিকেট না বানিয়ে আসল ফল ফেরত দিন।

৮. নিরাপত্তার মৌলিক

• শুধু HTTPS ব্যবহার করুন।
• Request authenticate করুন (token, API key, OAuth) এবং নির্দিষ্ট resource-এর বিরুদ্ধে প্রতিটি request authorise করুন। /orders/43 অন্য কারও হলে লগইন করা user তা পড়তে পারবে না (খুব প্রচলিত bug, BOLA বা IDOR বলা হয়)।
• সব ইনপুট যাচাই করুন: type, দৈর্ঘ্য, পরিসর, অনুমোদিত মান।
• যে field সেট করার কথা ভাবেননি তা গ্রহণ করবেন না (mass assignment)। স্পষ্ট allow-list ব্যবহার করুন।
• Rate limit ও request আকারের সীমা দিন।
• URL-এ secret রাখবেন না, কারণ তা log-এ যায়।
• Client-এর দরকারি field-ই ফেরত দিন। অন্য ব্যবহারকারীর data বা ভেতরের ID অকারণে ফাঁস করবেন না।
• Browser API কল করলে CORS সংকীর্ণ কনফিগার করুন।

৯. ব্যবহারে আনন্দদায়ক করুন

• সামঞ্জস্যপূর্ণ নামকরণ (snake_case বা camelCase বেছে লেগে থাকুন)।
• তারিখে ISO 8601 ও UTC (2026-11-07T10:00:00Z) ব্যবহার করুন।
• ID-তে string এবং টাকার জন্য floating-point ভুল এড়াতে ক্ষুদ্রতম এককের পূর্ণসংখ্যা (বা decimal string) ব্যবহার করুন।
• Read-heavy data-র জন্য conditional request ও caching header (ETag, Cache-Control) সমর্থন করুন।
• উত্তর compress করুন।

১০. ডকুমেন্ট ও test

• OpenAPI দিয়ে API বর্ণনা করুন এবং interactive docs প্রকাশ করুন।
• Request, response ও error-এর উদাহরণ দিন।
• Contract ও integration test লিখুন।
• Changelog দিন।

দ্রুত checklist

• URL-এ noun, method-এ verb।
• সঠিক status code, সামঞ্জস্যপূর্ণ error।
• সর্বত্র pagination।
• Versioning ও deprecation পরিকল্পনা।
• প্রতিটি endpoint-এ auth, মালিকানা যাচাই, ইনপুট যাচাই।
• ঝুঁকিপূর্ণ POST-এ idempotency।
• OpenAPI docs ও test।

মূল কথা: resource মডেল করুন, method ও status code ঠিকভাবে ব্যবহার করুন, error ও নামকরণ সামঞ্জস্যপূর্ণ রাখুন, paginate করুন, version দিন, প্রতিটি request সুরক্ষিত করুন এবং উদাহরণসহ ডকুমেন্ট করুন।

---

প্রোগ্রামিং রোডম্যাপ সিরিজ, পর্ব ২ (ভাষা ও নকশা): 3 নম্বর (মোট 5)। আগের লেখা: JavaScript ও TypeScript রোডম্যাপ: প্রথম script থেকে full stack.