Claude Code ব্যবহার করে আচরণ থেকে OpenAPI তৈরি করুন, সততার সঙ্গে

কেন OpenAPI চুক্তি ড্রিফট করে (এবং কেন এটা গুরুত্বপূর্ণ)

OpenAPI চুক্তি হল আপনার API-এর একটি ভাগ করা বিবরণ: কোন এন্ডপয়েন্ট আছে, আপনি কী পাঠান, কী ফিরে পান, এবং ভুলগুলো কেমন দেখা দেয়। এটা সার্ভার এবং যেকোনো কলার (ওয়েব অ্যাপ, মোবাইল অ্যাপ, অথবা অন্য সার্ভিস) এর মধ্যে চুক্তি।

সমস্যা হল ড্রিফট। চলমান API বদলে যায়, কিন্তু স্পেসটি যায় না। কিংবা স্পেস “সবচেয়ে সুন্দর” দেখাতে পরিষ্কার করা হয়, আর বাস্তবায়ন অদ্ভুত ফিল্ড, অনুপস্থিত স্ট্যাটাস কোড, বা অসঙ্গত এরর শেপ ফিরিয়ে দেয়। সময়ের সাথে লোকেরা OpenAPI ফাইলের ওপর বিশ্বাস হারায়, এবং এটা আর কেবল অন্য একটি ডকুমেন্ট হয়ে যায় যাকে সবাই উপেক্ষা করে।

ড্রিফট সাধারণত স্বাভাবিক চাপে থেকে আসে: দ্রুত ফিক্স চালু হয় কিন্তু স্পেক আপডেট হয় না, একটি নতুন অপশনাল ফিল্ড “অস্থায়ী”ভাবে যোগ করা হয়, pagination বিকশিত হয়, বা টিমগুলো বিভিন্ন “সত্যের উৎস” (ব্যাকএন্ড কোড, Postman collection, এবং OpenAPI ফাইল) আপডেট করে।

সৎ রাখা মানে স্পেক বাস্তব আচরণের সঙ্গে মিলে। যদি API কখনো কখনো conflict-এ 409 দেয়, সেটা চুক্তিতে থাকা উচিত। যদি কোনো ফিল্ড nullable হয়, বলুন। যদি auth প্রয়োজন হয়, সেটা অস্পষ্ট রাখবেন না।

ভাল ওয়ার্কফ্লো আপনাকে দেবে:

• একটি OpenAPI ফাইল যা উদ্দেশ্য ও পর্যবেক্ষিত আচরণ প্রতিফলিত করে
• ড্রিফট দ্রুত ধরা পড়ার জন্য একটি সহজ চেক তালিকা, যাতে ক্লায়েন্ট ভাঙার আগে অবস্থান পায়
• কপি করে আপনার কোডবেসে বসানোর মতো স্পষ্ট ক্লায়েন্ট ও সার্ভার ভ্যালিডেশন উদাহরণ

শেষটির গুরুত্ব বড়: একটি চুক্তি কেবল তখনই সাহায্য করে যখন তা বাধ্যতামূলকভাবে মানা হয়। একটি সৎ স্পেক ও পুনরাবৃত্ত চেক “API ডকুমেন্টেশন” কে এমন কিছুতে রূপান্তর করে যোর ওপর টিমগুলো নির্ভর করতে পারে।

কেবল কোড থেকে নয় — উদ্দেশ্যভিত্তিক আচরণ থেকে শুরু করুন

যদি আপনি কোড পড়ে বা রুট কপি করে শুরু করেন, আপনার OpenAPI আজকের বিদ্যমান জিনিসগুলো বর্ণনা করবে, সেগুলোতে এমন কুইর্কও থাকবে যা আপনি প্রতিশ্রুতি দিতে চান না। বরং, যা কলারকে করা উচিত তা বর্ণনা করুন, তারপর স্পেক ব্যবহার করে যাচাই করুন ইমপ্লিমেন্টেশন মিলছে কি না।

YAML বা JSON লেখার আগে, প্রতি এন্ডপয়েন্টে কয়টা ছোট কিন্তু স্পষ্ট факт সংগ্রহ করুন:

• এটা কী করে (মethode এবং path)
• কি গ্রহণ করে (headers, query, path params, body)
• কি রিটার্ন করে (সাফল্য স্ট্যাটাস কোড, রেসপন্স শেপ, প্রধান হেডার)
• কি ব্যর্থ হতে পারে (সম্ভাব্য এরর, স্ট্যাটাস কোড, এরর বডির শেপ)
• কে কল করতে পারে (auth ও roles, যদি প্রাসঙ্গিক)

তারপর আচরণ উদাহরণ হিসেবে লিখুন। উদাহরণগুলো আপনাকে পরিশেষে নির্দিষ্ট হতে বাধ্য করে এবং একটি সঙ্গতচুক্তি খসড়া করা সহজ করে।

উদাহরণস্বরূপ Tasks API-এর জন্য একটি হ্যাপি-পাথ হতে পারে: “title দিয়ে একটি task তৈরি করুন এবং id, title, status, এবং createdAt ফেরত পান।” সাধারণ ব্যর্থতা যোগ করুন: “title অনুপস্থিত হলে 400 দেয় { "error": "title is required" }” এবং “auth না থাকলে 401।” যদি আপনার কাছে এজ-কেস জানা থাকে তা যোগ করুন: duplicate title অনুমোদিত কি না, এবং যখন কোনো task ID পাওয়া না যায় তখন কি ঘটে।

নিয়মগুলো সহজ বাক্যে ধরুন যা কোড ডিটেইলের উপর নির্ভর করে না:

• “title আবশ্যক এবং 1–120 অক্ষরের।”
• “List সর্বোচ্চ 50 আইটেম ফেরত দেয় যদি না limit সেট করা থাকে (সর্বোচ্চ 200)।”
• “dueDate ISO 8601 date-time।”
• “Write এন্ডপয়েন্টগুলোর জন্য user token প্রয়োজন।”

শেষে, আপনার v1 স্কোপ নির্ধারণ করুন। অনিশ্চিত হলে v1 ছোট ও পরিষ্কার রাখুন (create, read, list, update status)। search, bulk updates, এবং জটিল filters পরে যোগ করুন যাতে চুক্তি বিশ্বাসযোগ্য থাকে।

এন্ডপয়েন্ট বর্ণনার জন্য একটি হালকা টেমপ্লেট

Claude Code-কে স্পেক লিখতে বলার আগে স্বল্প, পুনরাবৃত্তযোগ্য ফরম্যাটে behavior notes লিখুন। লক্ষ্য হলো ফাঁক গুলোতে ভুল করে অনুমান করে ভর্তি করা কঠিন করা।

একটি ভালো টেমপ্লেট যথেষ্ট ছোট হওয়া উচিত যাতে আপনি ব্যবহার করবেন, কিন্তু ধারাবাহিক যাতে দুজনই একইভাবে একটি এন্ডপয়েন্ট বর্ণনা করতে পারেন। এটাকে ফোকাস রাখুন যে API কী করে, কিভাবে করা হয় না তার ওপর নয়।

Endpoint behavior note template

Use one block per endpoint:

METHOD + PATH:
Purpose (1 sentence):
Auth:
Request:
- Query:
- Headers:
- Body example (JSON):
Responses:
- 200 OK example (JSON):
- 4xx example (status + JSON):
Edge cases:
Data types (human terms):

কমপক্ষে একটি কনক্রিট request এবং দুইটি response লিখুন। স্ট্যাটাস কোড এবং বাস্তবসম্মত JSON বডি সহ ফিল্ড নাম দিন। যদি কোনো ফিল্ড optional হয়, একটি উদাহরণ দেখান যেখানে এটি অনুপস্থিত।

এজ-কেসগুলি স্পষ্টভাবে কল আউট করুন। এগুলোই সেই জায়গা যেখানে স্পেক পরে অবিশ্বাস্য হয়ে যায় কারণ সবাই আলাদাভাবে কিছু ধরে নিয়েছে: খালি ফলাফল, অবৈধ IDs (400 বনাম 404), duplicates (409 বনাম idempotent আচরণ), ভ্যালিডেশন ব্যর্থতা, এবং pagination সীমা।

স্কিমার চিন্তা করার আগে plain শব্দে ডেটা টাইপগুলো নোট করুন: strings বনাম numbers, date-time ফরম্যাট, booleans, এবং enums (অনুমোদিত মানগুলোর তালিকা)। এটি একটি “সুন্দর” স্কিমা তৈরির থেকে রোধ করে যা বাস্তব পে-লোডের সাথে মিলবে না।

Claude Code দিয়ে OpenAPI স্পেক খসড়া করা (কার্যকর prompting)

Claude Code সবচেয়ে ভাল কাজ করে যখন আপনি এটিকে একটি যত্নশীল লেখকের মতো ব্যবহার করেন। আপনার behavior notes এবং স্পেক কিভাবে হবে তার কঠোর নিয়ম দিন। শুধু “একটি OpenAPI স্পেক লেখ” বললে সাধারণত অনুমান, অসঙ্গত নামকরণ, এবং অনুপস্থিত এরর কেস পাবেন।

আপনার behavior notes প্রথমে পেস্ট করুন, তারপর একটি টাইট ইনস্ট্রাকশন ব্লক যোগ করুন। একটি ব্যবহারযোগ্য প্রম্পট দেখতে এমন:

You are generating an OpenAPI 3.1 YAML spec.
Source of truth: the behavior notes below. Do not invent endpoints or fields.
If anything is unclear, list it under ASSUMPTIONS and leave TODO markers in the spec.

Requirements:
- Include: info, servers (placeholder), tags, paths, components/schemas, components/securitySchemes.
- For each operation: operationId, tags, summary, description, parameters, requestBody (when needed), responses.
- Model errors consistently with a reusable Error schema and reference it in 4xx/5xx responses.
- Keep naming consistent: PascalCase schema names, lowerCamelCase fields, stable operationId pattern.

Behavior notes:
[PASTE YOUR NOTES HERE]

Output only the OpenAPI YAML, then a short ASSUMPTIONS list.

খসড়া পাওয়ার পরে ASSUMPTIONS প্রথমে স্ক্যান করুন। সৎ হওয়ার জায়গা সেখানে নির্ধারিত হয়। যা সঠিক সেগুলো অনুমোদন করুন, ভুল ঠিক করুন, এবং আপডেটেড নোট নিয়ে পুনরায় চালান।

নামকরণ ধারাবাহিক রাখতে conventions upfront বলুন এবং সেই অনুযায়ী থাকুন। উদাহরণ: একটি স্থিতিশীল operationId প্যাটার্ন, noun-only tag নাম, singular schema নাম, একটি শেয়ার্ড Error schema, এবং একটা auth scheme নাম যা সবার কাছে ব্যবহার করা হবে।

কিছুভাবে Koder.ai মত vibe-coding ওয়ার্কস্পেসে কাজ করলে YAML ফাইলটি তাড়াতাড়ি একটি প্রকৃত ফাইল হিসেবে সংরক্ষণ করলে ছোট ডিফে iterate করা সহজ হয়। আপনি দেখতে পাবেন কোন পরিবর্তন অনুমোদিত behavior সিদ্ধান্ত থেকে এসেছে এবং কোনটা মডেল অনুমান করে দেয়।

স্পেকটি চলন্ত API-র সাথে তুলনা করার আগে ভ্যালিডেট করুন

প্রোডাকশনের সাথে তুলনা করার আগে OpenAPI ফাইলটি অভ্যন্তরীণভাবে সঙ্গতিপূর্ণ কিনা তা নিশ্চিত করুন। এখানে দ্রুতই আশা-ভুল ধরা যায়।

প্রতিটি এন্ডপয়েন্ট যেন আপনি ক্লায়েন্ট ডেভেলপার হিসেবে পড়ছেন। ফোকাস করুন কলারকে কি পাঠাতে হবে এবং তারা কি প্রত্যাশা করতে পারে।

একটি বাস্তবসম্মত রিভিউ পাস:

• Required বনাম optional: required ফিল্ডগুলো সঠিকভাবে চিহ্নিত করুন এবং “সবকিছু optional” থেকে বিরত থাকুন।
• Types ও formats: UUIDs, emails, date-time, min/max মান স্পষ্ট করুন।
• Examples: প্রতিটি এন্ডপয়েন্টে কমপক্ষে একটি বাস্তব অনুরোধ এবং রেসপন্স উদাহরণ রাখুন, এবং উদাহরণগুলো schemas-এর সাথে মিলিয়ে রাখুন।
• Status codes: আপনার behavior notes-এর সাথে সামঞ্জস্য করুন (create সাধারণত 201, 200 নয়)। 400 বনাম 422 নির্বাচন করুন এবং ধারাবাহিক থাকুন।
• Auth: প্রতিটি এন্ডপয়েন্টে কি প্রয়োজন তা স্পষ্ট করুন এবং রোলগুলো অ্যাক্সেসে প্রভাব ফেলে কিনা উল্লেখ করুন।

এরর রেসপন্সগুলো অতিরিক্ত যত্ন দাবি করে। একটি শেয়ার্ড শেপ বেছে নিন এবং সারাবিশ্বে reuse করুন। কিছু টিম খুবই সাদাসিধে রাখে ({ error: string }), অন্যরা অবজেক্ট ব্যবহার করে ({ error: { code, message, details } })। দুইটাই কাজ করতে পারে, কিন্তু এন্ডপয়েন্টগুলোর মধ্যে মিশাবেন না। মিশ্রণ হলে ক্লায়েন্ট কোডে বিশেষ কেস জমা হবে।

একটি দ্রুত স্যানিটি সিনারিও উপকারী: যদি POST /tasks এ title আবশ্যক থাকে, তাহলে স্কিমায় এটিকে required হিসেবে চিহ্নিত করা উচিত, ব্যর্থ রেসপন্সে আপনি যে এরর বডি আসলে ফেরত দেন সেটা দেখানো উচিত, এবং অপারেশনটি স্পষ্টভাবে বলে রাখা উচিত auth প্রয়োজন।

স্পেককে চলমান API ইমপ্লিমেন্টেশনের সাথে তুলনা করুন

স্পেক পড়ে আপনার উদ্দেশ্যগত আচরণ ঠিকঠাক লাগলে, চলমান API-কে বাস্তব অভিজ্ঞতা হিসেবে ব্যবহার করুন। লক্ষ্যটি “স্পেক জিতুক” নয় — বরং যোগসূত্রগুলো দ্রুত উন্মোচন করা এবং প্রতিটি বিষয়ে পরিষ্কার সিদ্ধান্ত নেয়া।

প্রথম পাসে, বাস্তব অনুরোধ/রেসপন্স স্যাম্পল সাধারণত সবচেয়ে সহজ বিকল্প। লগ এবং অটোমেটেড টেস্টও কাজ করে যদি তারা নির্ভরযোগ্য হয়।

সাধারণ অসামঞ্জস্য দেখুন: একটি জায়গায় উপস্থিত এন্ডপয়েন্ট আর অন্যত্র নেই, ফিল্ড নাম বা আকার ভিন্ন, স্ট্যাটাস কোড ভিন্ন (200 বনাম 201, 400 বনাম 422), অননুমোদিত আচরণ (pagination, sorting, filtering), এবং auth অসামঞ্জস্য (স্পেক বলে public কিন্তু কোড টোকেন চায়)।

উদাহরণ: OpenAPI বলছে POST /tasks 201 ফিরিয়ে দেয় {id,title}। আপনি চলমান API কল করলে 200 পান এবং {id,title,createdAt}। যদি আপনি স্পেক থেকে SDK জেনারেট করেন, সেটি “কাছাকাছি” নয় — এটি সমস্যা তৈরি করবে।

কোনোও কিছু সম্পাদনা করার আগে, সিদ্ধান্ত নিন কিভাবে মিমাংশা করবেন:

• যদি আচরণ সঠিক কিন্তু ডকুমেন্টেড নয়: স্পেক ঠিক করুন।
• যদি স্পেকই চুক্তি: কোড ঠিক করুন যাতে মিলে যায়।
• যদি দুটোই সঠিক না: প্রথমে intended behavior ঠিক করুন, তারপর উভয় আপডেট করুন।

প্রতিটি পরিবর্তন ছোট ও রিভিউযোগ্য রাখুন: এক এন্ডপয়েন্ট, এক রেসপন্স, এক স্কিমা টুইক। পর্যালোচনা ও পুনরায় টেস্ট করা সহজ হয়।

চুক্তি থেকে ক্লায়েন্ট ও সার্ভার ভ্যালিডেশন উদাহরণ তৈরি করুন

একবার আপনি এমন একটি স্পেক পেয়েছেন যা বিশ্বাসযোগ্য, সেটি ছোট ভ্যালিডেশন উদাহরণে রূপান্তর করুন। এটি হল যা ড্রিফট পুনরায় প্রবেশ করতে দেয় না।

সার্ভার-সাইড ভ্যালিডেশন (ভুল অনুরোধ প্রত্যাখ্যান করা)

সার্ভারে ভ্যালিডেশন মানে হল চুক্তি না মানা অনুরোধগুলি দ্রুত প্রত্যাখ্যান করা এবং একটি পরিষ্কার এরর ফেরত দেয়া। এটি আপনার ডেটা রক্ষা করে এবং বাগগুলো খুঁজে পাওয়া সহজ করে।

সার্ভার ভ্যালিডেশন উদাহরণগুলি তিনটি অংশে লিখুন: ইনপুট, প্রত্যাশিত আউটপুট, এবং প্রত্যাশিত এরর (একটি এরর কোড বা মেসেজ প্যাটার্ন, পুরো টেক্সট নয়)।

Example (চুক্তি বলে title আবশ্যক এবং 1–120 অক্ষর):

{
  "name": "Create task without title returns 400",
  "request": {"method": "POST", "path": "/tasks", "body": {"title": ""}},
  "expect": {"status": 400, "body": {"error": {"code": "VALIDATION_ERROR"}}}
}

ক্লায়েন্ট-সাইড ভ্যালিডেশন (ব্রেকিং পরিবর্তন আগেই ধরবে)

ক্লায়েন্ট-পাশে ভ্যালিডেশন হল সার্ভার পরিবর্তনের আগেই ড্রিফট ধরার কৌশল। যদি সার্ভার অন্য রকম শেপ ফেরত দেয় বা একটি required ফিল্ড হারিয়ে যায়, আপনার টেস্টগুলো সেটা ফ্ল্যাগ করবে।

ক্লায়েন্ট চেকগুলোকে ফোকাসড রাখুন — যেগুলোর উপর আপনি সত্যিই নির্ভর করেন, যেমন “একটি task-এ id, title, status আছে।” প্রতিটি অপশনাল ফিল্ড টেকসই না করে রাখুন।

কয়েকটি নির্দেশিকা:

• সম্পূর্ণ মানের চেয়ে উপস্থিতি ও টাইপ চেক করা ভালো।
• প্রয়োজনীয় ফিল্ডগুলোই assert করুন যদি না কোনো অপশনাল ফিল্ড আপনার ফিচারের জন্য গুরুত্বপূর্ণ হয়।
• এররগুলোর জন্য স্ট্যাটাস এবং একটি এরর কোড চেক করুন, পুরো মেসেজ নয়।
• অতিরিক্ত ফিল্ডগুলিকে অনুমতি দিন যতক্ষণ না চুক্তি তা স্পষ্টভাবে বিরুদ্ধ বলে।

Koder.ai-তে কাজ করলে আপনি এই উদাহরণ কেসগুলো OpenAPI ফাইলের পাশে রাখতে পারেন এবং আচরণ বদলালে একই রিভিউতে আপডেট করতে পারেন।

উদাহরণ দৃশ্যকল্প: একটি সাধারণ Tasks API শুরু থেকে শেষ পর্যন্ত

একটি ছোট API কল্পনা করুন যার তিনটি এন্ডপয়েন্ট আছে: POST /tasks একটি টাস্ক তৈরি করে, GET /tasks টাস্ক তালিকা করে, এবং GET /tasks/{id} একটি টাস্ক রিটার্ন করে।

একটি এন্ডপয়েন্টের জন্য কয়েকটি কনক্রিট উদাহরণ লিখে শুরু করুন, যেন আপনি একজন টেস্টারকে ব্যাখ্যা করছেন।

POST /tasks-এর উদ্দেশ্য হতে পারে:

• Success: { "title": "Buy milk" } পাঠালে 201 ফেরত দেয় একটি নতুন task অবজেক্ট সহ, যার মধ্যে id, title, এবং done:false থাকবে।
• Failure 1: {} পাঠালে 400 ফেরত দেয় { "error": "title is required" }।
• Failure 2: { "title": "x" } (খুব ছোট) পাঠালে 422 ফেরত দেয় { "error": "title must be at least 3 characters" }।

Claude Code যখন OpenAPI খসড়া করবে, এই এন্ডপয়েন্টের স্নিপেটটি স্কিমা, স্ট্যাটাস কোড, এবং বাস্তব উদাহরণগুলো ধরতে হবে:

paths:
  /tasks:
    post:
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            examples:
              ok:
                value: { "title": "Buy milk" }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              examples:
                created:
                  value: { "id": "t_123", "title": "Buy milk", "done": false }
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingTitle:
                  value: { "error": "title is required" }
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tooShort:
                  value: { "error": "title must be at least 3 characters" }

একটি সাধারণ অসামঞ্জস্য সূক্ষ্ম হতে পারে: চলমান API 200 দেয় 201-এর বদলে, অথবা { "taskId": 123 } ফেরায় { "id": "t_123" }-এর বদলে। সেই ধরনের “প্রায় একই” পার্থক্য জেনারেট করা ক্লায়েন্ট ভেঙে দেয়।

সমাধান করুন একটি সত্য সূত্র বেছে নিয়ে। যদি intended behavior সঠিক হয়, ইমপ্লিমেন্টেশন পরিবর্তন করে 201 ও সম্মত Task শেপ ফিরিয়ে দিন। যদি প্রোডাকশন আচরণ আগে থেকেই নির্ভরতার অংশ হয়, স্পেক আপডেট করুন (এবং behavior notes) বাস্তবতা মেলে যেন ক্লায়েন্ট অবাক না হয়।

সাধারণ ভুলযুগল যা চুক্তিটিকে অসত্‍ করে দেয়

চুক্তি অসৎ হয়ে যায় যখন এটা নিয়মগুলো বর্ণনা করা বন্ধ করে এবং কেবল আপনার API একদিন যে রিসপন্স দিয়েছিল তাই বর্ণনা করে। একটি সহজ টেস্ট: একটি নতুন ইমপ্লিমেন্টেশন কি এই স্পেক পাস করতে পারবে আজকের কুইর্কগুলো কপি না করে? যদি হ্যাঁ — চুক্তি অসৎ।

এক ফাঁক হল overfitting। আপনি একটি রেসপন্স ধরেন এবং এটিতে আইন বানিয়ে দেন। উদাহরণ: আপনার API বর্তমানে প্রতিটি টাস্কে dueDate: null দেয়, তাই স্পেক বলে ফিল্ডটি সবসময় nullable। কিন্তু বাস্তব নিয়ম হতে পারে “status scheduled হলে required।” চুক্তিটি নিয়মটি প্রকাশ করা উচিত, কেবল বর্তমান ডেটাসেট নয়।

এররগুলোতে সততা প্রায়ই ভাঙ্গে। কেবল সফল রেসপন্স স্পেক করার লোভ থাকে কারণ সেগুলো সুন্দর দেখায়। কিন্তু ক্লায়েন্টদের মৌলিকগুলো জানা দরকার: token না থাকলে 401, forbidden হলে 403, অজানা ID-তে 404, এবং একটি ধারাবাহিক validation error (400 বা 422)।

অন্য বিপজ্জনক প্যাটার্ন:

• নাম ও টাইপ এন্ডপয়েন্ট অনুযায়ী ভিন্ন হয়ে যায় (taskId একটি রুটে কিন্তু অন্যটিতে id, বা priority এক রেসপন্সে string এবং অন্যটিতে number)।
• উদাহরণ ও স্কিমা বিপরীতমুখী (enum মান মিলছে না, date-time উদাহরণ ISO 8601 নয়)।
• টেনে-টান decision এড়াতে টাইপগুলো বিস্তৃত করা (সবকিছু string, সবকিছু optional)।
• স্পেক মার্কেটিং কপির মতো পড়ে (“fast,” “secure”) — টেস্টেবল চুক্তি না।

ভালো চুক্তি টেস্টেবল। যদি আপনি স্পেক থেকে একটি ব্যর্থ টেস্ট লিখতে না পারেন, তখন সেটি এখনও সৎ নয়।

দ্রুত চেকলিস্ট — শেয়ার বা প্রকাশের আগে

OpenAPI ফাইল অন্য টিমকে দেওয়ার আগে (বা ডকসে পেস্ট করার আগে) দ্রুত পরীক্ষা করুন: "কেউ এটা পড়ে আপনার মনের কথা না পড়েই ব্যবহার করতে পারবে কি?"

উদাহরণ দিয়ে শুরু করুন। একটি স্পেক বৈধ হলেও যদি প্রতিটি অনুরোধ ও রেসপন্স abstract হয় তাহলে সেটি অনুপযোগী। প্রতিটি অপারেশনের জন্য কমপক্ষে একটি বাস্তব অনুরোধ উদাহরণ এবং একটি সফল রেসপন্স উদাহরণ যোগ করুন। এররগুলোর জন্য auth ও ভ্যালিডেশন মিস হলে প্রতিটি সাধারণ ব্যর্থতার জন্য একটি উদাহরণ যথেষ্ট।

তারপর ধারাবাহিকতা পরীক্ষা করুন। যদি এক এন্ডপয়েন্ট { "error": "..." } ফেরায় এবং অন্যটি { "message": "..." }, ক্লায়েন্ট কবে যে শাখায় পড়বে সেটা জানবে না। একটি একক এরর শেপ বেছে নিন এবং সেটি পুনরায় ব্যবহার করুন, সাথে predictable status codes।

চেকলিস্ট সংক্ষেপে:

• Required fields, formats (email, uuid, date-time), এবং enums স্পষ্ট
• Status codes অনুত্তীর্ণ এবং সাদৃশ্যময় একই ধরনের এন্ডপয়েন্টে
• Error responses schema ও examples উভয়ই আছে
• প্রতিটি এন্ডপয়েন্টে 2-3টি বাস্তব কল রান করে (tests, curl, Postman, অথবা লগ) এবং স্পেকের সাথে তুলনা করা হয়েছে
• আপনি স্পেক থেকে একটি ছোট ক্লায়েন্ট কল লিখতে পারেন হেডার, ফিল্ড নাম, বা nullability অনুমান না করে

একটি ব্যবহারিক ট্রিক: একটি এন্ডপয়েন্ট বেছে নিন, কল্পনা করুন আপনি কখনই API দেখেননি, এবং উত্তর দিন: "আমি কী পাঠাব, কি পাব, আর কি ভেঙে পড়বে?" যদি OpenAPI এটা পরিষ্কারভাবে বলতে না পারে, সেটা প্রস্তুত নয়।

পরবর্তী ধাপ: অভ্যাস করুন (এবং পরিবর্তন নিরাপদ রাখুন)

এই ওয়ার্কফ্লো তখনই ফল দেয় যখন এটি নিয়মিত চালানো হয়, কেবল রিলিজের আগে নয়। একটি সহজ নিয়ম নিন এবং তাতে স্থির থাকুন: যখনই একটি এন্ডপয়েন্ট বদলে, চালান; আবার রিলিজের আগে চালান।

ওনারশিপ সাদাসিধে রাখুন। যে ব্যক্তি একটি এন্ডপয়েন্ট পরিবর্তন করে সে behavior notes ও স্পেক খসড়া আপডেট করবে। দ্বিতীয় একজন ব্যক্তি “স্পেক বনাম ইমপ্লিমেন্টেশন” ডিফ রিভিউ করবে ঠিক যেমন কোড রিভিউ। QA বা সাপোর্ট টিমেরা ভালো রিভিউয়ার হয়ে উঠতে পারে কারণ তারা অস্পষ্ট রেসপন্স ও এজ-কেস দ্রুত ধরতে পারে।

চুক্তি সম্পাদনাগুলোকে কোড এডিটের মতোই বিবেচনা করুন। যদি আপনি chat-driven builder যেমন Koder.ai ব্যবহার করেন, ঝুঁকিপূর্ণ edits-এর আগে snapshot নিন এবং রোলব্যাক ব্যবহার করুন যখন দরকার। Koder.ai সোর্স কোড export করার সুবিধা দেয়, যা স্পেক ও ইমপ্লিমেন্টেশন একসাথে আপনার repo-তে রাখা সহজ করে।

একটি কার্যকর রুটিন সাধারণত ধীর নয়:

• নতুন এন্ডপয়েন্ট লিখলে behavior notes তৈরি করুন
• OpenAPI ভ্যালিডেট করুন এবং contract tests merge করার আগে চালান
• রিলিজের আগে স্পেক বনাম চলমান API তুলুন
• ঝুঁকিপূর্ণ edits-এর আগে snapshot নিন; diff যদি কনফিউজিং হয় rollback করুন

পরবর্তী কাজ: একটি বিদ্যমান এন্ডপয়েন্ট বেছে নিন। 5–10 লাইন behavior notes লিখুন (ইনপুট, আউটপুট, এরর কেস), সেই নোট থেকে একটি খসড়া OpenAPI জেনারেট করুন, ভ্যালিডেট করুন, তারপর চলমান ইমপ্লিমেন্টেশনের সাথে তুলনা করুন। একটি মিম্যাচ ঠিক করুন, পুনরায় টেস্ট করুন, আর পুনরাবৃত্তি করুন। এক এন্ডপয়েন্টের পরে অভ্যাস সাধারণত টিকে যায়।