Claude Code ব্যবহার করে আচরণ থেকে OpenAPI কীভাবে তৈরি করবেন, তারপর সেটি আপনার API ইমপ্লিমেন্টেশনের সাথে তুলনা করবেন এবং সহজ ক্লায়েন্ট ও সার্ভার ভ্যালিডেশন উদাহরণ তৈরি করবেন তা শিখুন।
OpenAPI চুক্তি হল আপনার API-এর একটি ভাগ করা বিবরণ: কোন এন্ডপয়েন্ট আছে, আপনি কী পাঠান, কী ফিরে পান, এবং ভুলগুলো কেমন দেখা দেয়। এটা সার্ভার এবং যেকোনো কলার (ওয়েব অ্যাপ, মোবাইল অ্যাপ, অথবা অন্য সার্ভিস) এর মধ্যে চুক্তি।
সমস্যা হল ড্রিফট। চলমান API বদলে যায়, কিন্তু স্পেসটি যায় না। কিংবা স্পেস “সবচেয়ে সুন্দর” দেখাতে পরিষ্কার করা হয়, আর বাস্তবায়ন অদ্ভুত ফিল্ড, অনুপস্থিত স্ট্যাটাস কোড, বা অসঙ্গত এরর শেপ ফিরিয়ে দেয়। সময়ের সাথে লোকেরা OpenAPI ফাইলের ওপর বিশ্বাস হারায়, এবং এটা আর কেবল অন্য একটি ডকুমেন্ট হয়ে যায় যাকে সবাই উপেক্ষা করে।
ড্রিফট সাধারণত স্বাভাবিক চাপে থেকে আসে: দ্রুত ফিক্স চালু হয় কিন্তু স্পেক আপডেট হয় না, একটি নতুন অপশনাল ফিল্ড “অস্থায়ী”ভাবে যোগ করা হয়, pagination বিকশিত হয়, বা টিমগুলো বিভিন্ন “সত্যের উৎস” (ব্যাকএন্ড কোড, Postman collection, এবং OpenAPI ফাইল) আপডেট করে।
সৎ রাখা মানে স্পেক বাস্তব আচরণের সঙ্গে মিলে। যদি API কখনো কখনো conflict-এ 409 দেয়, সেটা চুক্তিতে থাকা উচিত। যদি কোনো ফিল্ড nullable হয়, বলুন। যদি auth প্রয়োজন হয়, সেটা অস্পষ্ট রাখবেন না।
ভাল ওয়ার্কফ্লো আপনাকে দেবে:
শেষটির গুরুত্ব বড়: একটি চুক্তি কেবল তখনই সাহায্য করে যখন তা বাধ্যতামূলকভাবে মানা হয়। একটি সৎ স্পেক ও পুনরাবৃত্ত চেক “API ডকুমেন্টেশন” কে এমন কিছুতে রূপান্তর করে যোর ওপর টিমগুলো নির্ভর করতে পারে।
যদি আপনি কোড পড়ে বা রুট কপি করে শুরু করেন, আপনার OpenAPI আজকের বিদ্যমান জিনিসগুলো বর্ণনা করবে, সেগুলোতে এমন কুইর্কও থাকবে যা আপনি প্রতিশ্রুতি দিতে চান না। বরং, যা কলারকে করা উচিত তা বর্ণনা করুন, তারপর স্পেক ব্যবহার করে যাচাই করুন ইমপ্লিমেন্টেশন মিলছে কি না।
YAML বা JSON লেখার আগে, প্রতি এন্ডপয়েন্টে কয়টা ছোট কিন্তু স্পষ্ট факт সংগ্রহ করুন:
তারপর আচরণ উদাহরণ হিসেবে লিখুন। উদাহরণগুলো আপনাকে পরিশেষে নির্দিষ্ট হতে বাধ্য করে এবং একটি সঙ্গতচুক্তি খসড়া করা সহজ করে।
উদাহরণস্বরূপ Tasks API-এর জন্য একটি হ্যাপি-পাথ হতে পারে: “title দিয়ে একটি task তৈরি করুন এবং id, title, status, এবং createdAt ফেরত পান।” সাধারণ ব্যর্থতা যোগ করুন: “title অনুপস্থিত হলে 400 দেয় { "error": "title is required" }” এবং “auth না থাকলে 401।” যদি আপনার কাছে এজ-কেস জানা থাকে তা যোগ করুন: duplicate title অনুমোদিত কি না, এবং যখন কোনো task ID পাওয়া না যায় তখন কি ঘটে।
নিয়মগুলো সহজ বাক্যে ধরুন যা কোড ডিটেইলের উপর নির্ভর করে না:
title আবশ্যক এবং 1–120 অক্ষরের।”limit সেট করা থাকে (সর্বোচ্চ 200)।”dueDate ISO 8601 date-time।”শেষে, আপনার v1 স্কোপ নির্ধারণ করুন। অনিশ্চিত হলে v1 ছোট ও পরিষ্কার রাখুন (create, read, list, update status)। search, bulk updates, এবং জটিল filters পরে যোগ করুন যাতে চুক্তি বিশ্বাসযোগ্য থাকে।
Claude Code-কে স্পেক লিখতে বলার আগে স্বল্প, পুনরাবৃত্তযোগ্য ফরম্যাটে behavior notes লিখুন। লক্ষ্য হলো ফাঁক গুলোতে ভুল করে অনুমান করে ভর্তি করা কঠিন করা।
একটি ভালো টেমপ্লেট যথেষ্ট ছোট হওয়া উচিত যাতে আপনি ব্যবহার করবেন, কিন্তু ধারাবাহিক যাতে দুজনই একইভাবে একটি এন্ডপয়েন্ট বর্ণনা করতে পারেন। এটাকে ফোকাস রাখুন যে API কী করে, কিভাবে করা হয় না তার ওপর নয়।
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 সবচেয়ে ভাল কাজ করে যখন আপনি এটিকে একটি যত্নশীল লেখকের মতো ব্যবহার করেন। আপনার 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 সিদ্ধান্ত থেকে এসেছে এবং কোনটা মডেল অনুমান করে দেয়।
প্রোডাকশনের সাথে তুলনা করার আগে OpenAPI ফাইলটি অভ্যন্তরীণভাবে সঙ্গতিপূর্ণ কিনা তা নিশ্চিত করুন। এখানে দ্রুতই আশা-ভুল ধরা যায়।
প্রতিটি এন্ডপয়েন্ট যেন আপনি ক্লায়েন্ট ডেভেলপার হিসেবে পড়ছেন। ফোকাস করুন কলারকে কি পাঠাতে হবে এবং তারা কি প্রত্যাশা করতে পারে।
একটি বাস্তবসম্মত রিভিউ পাস:
এরর রেসপন্সগুলো অতিরিক্ত যত্ন দাবি করে। একটি শেয়ার্ড শেপ বেছে নিন এবং সারাবিশ্বে reuse করুন। কিছু টিম খুবই সাদাসিধে রাখে ({ error: string }), অন্যরা অবজেক্ট ব্যবহার করে ({ error: { code, message, details } })। দুইটাই কাজ করতে পারে, কিন্তু এন্ডপয়েন্টগুলোর মধ্যে মিশাবেন না। মিশ্রণ হলে ক্লায়েন্ট কোডে বিশেষ কেস জমা হবে।
একটি দ্রুত স্যানিটি সিনারিও উপকারী: যদি POST /tasks এ title আবশ্যক থাকে, তাহলে স্কিমায় এটিকে required হিসেবে চিহ্নিত করা উচিত, ব্যর্থ রেসপন্সে আপনি যে এরর বডি আসলে ফেরত দেন সেটা দেখানো উচিত, এবং অপারেশনটি স্পষ্টভাবে বলে রাখা উচিত auth প্রয়োজন।
স্পেক পড়ে আপনার উদ্দেশ্যগত আচরণ ঠিকঠাক লাগলে, চলমান API-কে বাস্তব অভিজ্ঞতা হিসেবে ব্যবহার করুন। লক্ষ্যটি “স্পেক জিতুক” নয় — বরং যোগসূত্রগুলো দ্রুত উন্মোচন করা এবং প্রতিটি বিষয়ে পরিষ্কার সিদ্ধান্ত নেয়া।
প্রথম পাসে, বাস্তব অনুরোধ/রেসপন্স স্যাম্পল সাধারণত সবচেয়ে সহজ বিকল্প। লগ এবং অটোমেটেড টেস্টও কাজ করে যদি তারা নির্ভরযোগ্য হয়।
সাধারণ অসামঞ্জস্য দেখুন: একটি জায়গায় উপস্থিত এন্ডপয়েন্ট আর অন্যত্র নেই, ফিল্ড নাম বা আকার ভিন্ন, স্ট্যাটাস কোড ভিন্ন (200 বনাম 201, 400 বনাম 422), অননুমোদিত আচরণ (pagination, sorting, filtering), এবং auth অসামঞ্জস্য (স্পেক বলে public কিন্তু কোড টোকেন চায়)।
উদাহরণ: OpenAPI বলছে POST /tasks 201 ফিরিয়ে দেয় {id,title}। আপনি চলমান API কল করলে 200 পান এবং {id,title,createdAt}। যদি আপনি স্পেক থেকে SDK জেনারেট করেন, সেটি “কাছাকাছি” নয় — এটি সমস্যা তৈরি করবে।
কোনোও কিছু সম্পাদনা করার আগে, সিদ্ধান্ত নিন কিভাবে মিমাংশা করবেন:
প্রতিটি পরিবর্তন ছোট ও রিভিউযোগ্য রাখুন: এক এন্ডপয়েন্ট, এক রেসপন্স, এক স্কিমা টুইক। পর্যালোচনা ও পুনরায় টেস্ট করা সহজ হয়।
একবার আপনি এমন একটি স্পেক পেয়েছেন যা বিশ্বাসযোগ্য, সেটি ছোট ভ্যালিডেশন উদাহরণে রূপান্তর করুন। এটি হল যা ড্রিফট পুনরায় প্রবেশ করতে দেয় না।
সার্ভারে ভ্যালিডেশন মানে হল চুক্তি না মানা অনুরোধগুলি দ্রুত প্রত্যাখ্যান করা এবং একটি পরিষ্কার এরর ফেরত দেয়া। এটি আপনার ডেটা রক্ষা করে এবং বাগগুলো খুঁজে পাওয়া সহজ করে।
সার্ভার ভ্যালিডেশন উদাহরণগুলি তিনটি অংশে লিখুন: ইনপুট, প্রত্যাশিত আউটপুট, এবং প্রত্যাশিত এরর (একটি এরর কোড বা মেসেজ প্যাটার্ন, পুরো টেক্সট নয়)।
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 আছে।” প্রতিটি অপশনাল ফিল্ড টেকসই না করে রাখুন।
কয়েকটি নির্দেশিকা:
Koder.ai-তে কাজ করলে আপনি এই উদাহরণ কেসগুলো OpenAPI ফাইলের পাশে রাখতে পারেন এবং আচরণ বদলালে একই রিভিউতে আপডেট করতে পারেন।
একটি ছোট API কল্পনা করুন যার তিনটি এন্ডপয়েন্ট আছে: POST /tasks একটি টাস্ক তৈরি করে, GET /tasks টাস্ক তালিকা করে, এবং GET /tasks/{id} একটি টাস্ক রিটার্ন করে।
একটি এন্ডপয়েন্টের জন্য কয়েকটি কনক্রিট উদাহরণ লিখে শুরু করুন, যেন আপনি একজন টেস্টারকে ব্যাখ্যা করছেন।
POST /tasks-এর উদ্দেশ্য হতে পারে:
{ "title": "Buy milk" } পাঠালে 201 ফেরত দেয় একটি নতুন task অবজেক্ট সহ, যার মধ্যে id, title, এবং done:false থাকবে।{} পাঠালে 400 ফেরত দেয় { "error": "title is required" }।{ "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)।string, সবকিছু optional)।ভালো চুক্তি টেস্টেবল। যদি আপনি স্পেক থেকে একটি ব্যর্থ টেস্ট লিখতে না পারেন, তখন সেটি এখনও সৎ নয়।
OpenAPI ফাইল অন্য টিমকে দেওয়ার আগে (বা ডকসে পেস্ট করার আগে) দ্রুত পরীক্ষা করুন: "কেউ এটা পড়ে আপনার মনের কথা না পড়েই ব্যবহার করতে পারবে কি?"
উদাহরণ দিয়ে শুরু করুন। একটি স্পেক বৈধ হলেও যদি প্রতিটি অনুরোধ ও রেসপন্স abstract হয় তাহলে সেটি অনুপযোগী। প্রতিটি অপারেশনের জন্য কমপক্ষে একটি বাস্তব অনুরোধ উদাহরণ এবং একটি সফল রেসপন্স উদাহরণ যোগ করুন। এররগুলোর জন্য auth ও ভ্যালিডেশন মিস হলে প্রতিটি সাধারণ ব্যর্থতার জন্য একটি উদাহরণ যথেষ্ট।
তারপর ধারাবাহিকতা পরীক্ষা করুন। যদি এক এন্ডপয়েন্ট { "error": "..." } ফেরায় এবং অন্যটি { "message": "..." }, ক্লায়েন্ট কবে যে শাখায় পড়বে সেটা জানবে না। একটি একক এরর শেপ বেছে নিন এবং সেটি পুনরায় ব্যবহার করুন, সাথে predictable status codes।
চেকলিস্ট সংক্ষেপে:
একটি ব্যবহারিক ট্রিক: একটি এন্ডপয়েন্ট বেছে নিন, কল্পনা করুন আপনি কখনই API দেখেননি, এবং উত্তর দিন: "আমি কী পাঠাব, কি পাব, আর কি ভেঙে পড়বে?" যদি OpenAPI এটা পরিষ্কারভাবে বলতে না পারে, সেটা প্রস্তুত নয়।
এই ওয়ার্কফ্লো তখনই ফল দেয় যখন এটি নিয়মিত চালানো হয়, কেবল রিলিজের আগে নয়। একটি সহজ নিয়ম নিন এবং তাতে স্থির থাকুন: যখনই একটি এন্ডপয়েন্ট বদলে, চালান; আবার রিলিজের আগে চালান।
ওনারশিপ সাদাসিধে রাখুন। যে ব্যক্তি একটি এন্ডপয়েন্ট পরিবর্তন করে সে behavior notes ও স্পেক খসড়া আপডেট করবে। দ্বিতীয় একজন ব্যক্তি “স্পেক বনাম ইমপ্লিমেন্টেশন” ডিফ রিভিউ করবে ঠিক যেমন কোড রিভিউ। QA বা সাপোর্ট টিমেরা ভালো রিভিউয়ার হয়ে উঠতে পারে কারণ তারা অস্পষ্ট রেসপন্স ও এজ-কেস দ্রুত ধরতে পারে।
চুক্তি সম্পাদনাগুলোকে কোড এডিটের মতোই বিবেচনা করুন। যদি আপনি chat-driven builder যেমন Koder.ai ব্যবহার করেন, ঝুঁকিপূর্ণ edits-এর আগে snapshot নিন এবং রোলব্যাক ব্যবহার করুন যখন দরকার। Koder.ai সোর্স কোড export করার সুবিধা দেয়, যা স্পেক ও ইমপ্লিমেন্টেশন একসাথে আপনার repo-তে রাখা সহজ করে।
একটি কার্যকর রুটিন সাধারণত ধীর নয়:
পরবর্তী কাজ: একটি বিদ্যমান এন্ডপয়েন্ট বেছে নিন। 5–10 লাইন behavior notes লিখুন (ইনপুট, আউটপুট, এরর কেস), সেই নোট থেকে একটি খসড়া OpenAPI জেনারেট করুন, ভ্যালিডেট করুন, তারপর চলমান ইমপ্লিমেন্টেশনের সাথে তুলনা করুন। একটি মিম্যাচ ঠিক করুন, পুনরায় টেস্ট করুন, আর পুনরাবৃত্তি করুন। এক এন্ডপয়েন্টের পরে অভ্যাস সাধারণত টিকে যায়।
OpenAPI drift হল যখন আপনার চলমান API আর OpenAPI ফাইলের সাথে মেলে না যা লোকেরা শেয়ার করে। স্পেসটিতে নতুন ফিল্ড, স্ট্যাটাস কোড, বা auth নিয়ম অনুপস্থিত থাকতে পারে, অথবা স্পেক “আদর্শ” আচরণ বর্ণনা করে যা সার্ভার পালন করে না.
এটি গুরুত্বপূর্ণ কারণ ক্লায়েন্ট (অ্যাপ, অন্যান্য সার্ভিস, জেনারেট করা SDK, টেস্ট) চুক্তির উপর ভিত্তি করে সিদ্ধান্ত নেয়, সার্ভারের “সাধারণ” আচরণের উপর নয়।
ক্লায়েন্টের পক্ষে ব্রেকেজগুলি অনিয়মিত এবং ডিবাগ করা কঠিন হয়ে যায়: একটি মোবাইল অ্যাপ 201 আশা করে কিন্তু 200 পায়, একটি SDK আর পার্স করতে পারে না কারণ একটি ফিল্ডের নাম পরিবর্তিত হয়েছে, অথবা এরর হ্যান্ডলিং ব্যর্থ হয় কারণ এরর শেপ আলাদা।
এমনকি যখন কিছু ক্র্যাশ করে না, টিমগুলো স্পেকের উপর থেকে বিশ্বাস হারিয়ে ফেলে এবং স্পেক ব্যবহার বন্ধ করে দেয় — ফলে প্রাথমিক সতর্কতা ব্যবস্থা চলে যায়।
কারণ কোড বর্তমান আচরণই প্রতিফলিত করে, যেখানে অনেক সময় অনিচ্ছাকৃত কুইর্ক থাকে যেগুলি আপনি দীর্ঘমেয়াদে প্রতিশ্রুতি দিতে চাইবেন না।
ভালো ডিফল্ট হল: প্রথমে intended behavior লিখুন (ইনপুট, আউটপুট, এরর), তারপর ইমপ্লিমেন্টেশন মিলছে কিনা যাচাই করুন। এতে আপনি একটি এমন চুক্তি পাবেন যা আপনি চালানো ও বাস্তবায়ন উভয় দিক থেকেই নিশ্চিত করতে পারবেন, কেবল আজকের রুটগুলোর স্ন্যাপশট নয়।
প্রতি এন্ডপয়েন্টের জন্য কমপক্ষে নিচেরগুলো ধরুন:
যদি আপনি একটি কনক্রেট রিকুয়েস্ট এবং দুইটি রেসপন্স লিখতে পারেন, সাধারণত স্পেস খসড়া করার জন্য যথেষ্ট।
একটি error বডির একটি ফরম্যাট বেছে নিন এবং সেটি সার্বজনীনভাবে ব্যবহার করুন।
সহজ একটা ডিফল্ট হতে পারে:
{ "error": "message" }, অথবা{ "error": { "code": "...", "message": "...", "details": ... } }এবং তারপর সেটি প্রতিটি এন্ডপয়েন্ট ও উদাহরণে একরকমভাবে পুনরায় ব্যবহার করুন। ধারাবাহিকতা জটিলতার চেয়ে বেশি গুরুত্বপূর্ণ, কারণ ক্লায়েন্টরা এ শেপকে হার্ড-কোড করবে।
Claude Code-কে আপনার behavior notes দিন এবং কড়া নিয়ম যোগ করুন, এবং বলুন কিছু বানাবেন না। একটি ব্যবহারযোগ্য নির্দেশাবলী সেট:
TODO in the spec and list it under ASSUMPTIONS.”Error) and reference them.”জেনারেশনের পরে প্রথমে পরীক্ষা করুন — অনুমানই ড্রিফটের শুরু।
স্পেকটি নিজেই যাচাই করুন:
201)এই ধাঁধা-পাস গুলো স্পিডে “ইচ্ছাপূর্ণ” OpenAPI ফাইল আটকাতে সহায় করে।
রানিং API-কে ধরা হোক যে ব্যবহারকারীরা আজ অভিজ্ঞ হল — প্রতিটি বিচ্ছেদে সিদ্ধান্ত নিন:
সব পরিবর্তন ছোট রাখুন (এক এন্ডপয়েন্ট বা এক রেসপন্স) যাতে দ্রুত পুনরায় টেস্ট করা যায়।
Server-side validation মানে অনুরোধটি চুক্তির সাথে মেলে না এমন ক্ষেত্রে দ্রুত ব্যর্থ করা এবং পরিষ্কার এরর ফেরত দেয়া (স্ট্যাটাস + এরর কোড/শেপ)।
Client-side validation হল সার্ভার বদলে যাওয়ার আগেই ড্রিফট ধরার উপায় — কেবল সেই ফিল্ড এবং টাইপগুলো চেক করুন যেগুলোর উপর আপনার ক্লায়েন্ট ভর করে।
নিচের guideline গুলো মনে রাখুন:
একটি সহজ রুটিন কাজ করে:
Koder.ai ব্যবহার করলে OpenAPI ফাইল কোডের পাশাপাশি রেখে snapshot ও rollback সুবিধা কাজে লাগে।