Versioning আর OpenAPI — চুক্তি লেখা আর docs

১ · পুরোনো অ্যাপ বদলানো যায় না

বাজারঘরের website আপনি একবার deploy করলে সবার browser পরের reload-এ নতুন কোড পায়। Mobile অ্যাপ এমন নয়। রহিমা চাচি বাজারঘরের Android অ্যাপ আট মাস আগে নামিয়েছেন। Update চালু নেই, ফোনে জায়গাও কম। তাঁর ফোনের কোডটি আপনার হাতের বাইরে, অথচ সেটি প্রতিদিন আপনার server ডাকছে। এক শুক্রবার আপনি ভাবলেন, দামকে পয়সায় রাখলে হিসাব পরিষ্কার হয়। price: 45 বদলে দিলেন price: 4500. Deploy শেষ, test সবুজ। রহিমা চাচির ফোনে এখন মরিচের দাম ৪,৫০০ টাকা।

এখানে চুক্তি মানে API-র সবকিছু: URL, method, ঘরের নাম, type, অর্থ, একক, error-এর আকার। পর্ব ২৯-এ আপনি code-এর ভেতরের স্তরগুলো interface দিয়ে আলাদা করেছেন। API হলো সেই একই ধারণা, কিন্তু অন্য পক্ষ আপনার repository-র বাইরে। ভেতরের interface বদলালে compiler সব জায়গা দেখিয়ে দেয়। বাইরের চুক্তি বদলালে কেউ দেখায় না, ব্যবহারকারী শুধু ভুল দাম দেখেন।

Web client নিয়েও একই ঝুঁকি কম মাত্রায় আছে। ব্যবহারকারী খোলা tab রেখে দেন, CDN পুরোনো JS ধরে রাখে, partner দোকান আপনার API দিয়ে নিজের সিস্টেম বানায়। তাই প্রশ্নটি “কীভাবে version দেব” দিয়ে শুরু নয়। প্রশ্নটি হলো: কোন বদল কাকে ভাঙবে?

REST resource, status code আর pagination এই মডিউলের পর্ব ৩২, ৩৩ আর ৩৪-এর বিষয়। এখানে সেগুলো আবার শেখানো হবে না। এই পর্বের প্রশ্ন একটিই: যা বানিয়েছেন, সেটি মানুষকে না ভেঙে কীভাবে বদলাবেন আর কীভাবে লিখে রাখবেন। তাত্ত্বিক ভিত্তি দেখতে চাইলে System Design-এর REST API নকশা পড়ুন।

২ · কোন বদল ভাঙে, কোনটি ভাঙে না

একটি সহজ নিয়ম মনে রাখুন। Response-এ আপনি কথা দেন, request-এ আপনি শর্ত দেন। কথা কমানো ভাঙন, শর্ত বাড়ানোও ভাঙন। উল্টো দিকে কথা বাড়ানো আর শর্ত কমানো সাধারণত নিরাপদ।

শেষ সারিটির একটি নাম আছে, Hyrum's Law. Google-এর প্রকৌশলী Hyrum Wright-এর নামে পরিচিত এই পর্যবেক্ষণ বলে, ব্যবহারকারী যথেষ্ট হলে আপনার সিস্টেমের প্রতিটি দৃশ্যমান আচরণের ওপর কেউ না কেউ নির্ভর করবে, আপনি কথা দিন বা না দিন। তাই তালিকাটি পূর্ণ গ্যারান্টি নয়। এটি ঝুঁকির মানচিত্র।

নিচের ধাপগুলোতে একই পুরোনো অ্যাপের সামনে দুই ধরনের বদল দেখুন। দুই রায়ই oasdiff নামের টুলের সত্যিকারের run থেকে নেওয়া, যা অংশ ৮-এ চালাব।

{"id":7,"name":"কাঁচা মরিচ","price":45}

পুরোনো অ্যাপের স্ক্রিন: মরিচ, ৪৫ টাকা

{"id":7,"name":"কাঁচা মরিচ","price":45,"unit":"কেজি"}

পুরোনো অ্যাপ unit চেনে না, উপেক্ষা করে:
মরিচ, ৪৫ টাকা

info [response-optional-property-added]
  in API GET /products/{id}
  added the optional property `unit`

breaking: No breaking changes to report

{"id":7,"name":"কাঁচা মরিচ","price":{"amount":4500,"currency":"BDT"}}

পুরোনো অ্যাপের স্ক্রিন:
মরিচ, [object Object] টাকা

error [response-property-type-changed]
  in API GET /products/{id}
  the `price` response's property `type`
  changed from `integer` to `object`
  for status `200`

/v1/products/7  → "price":45                অপরিবর্তিত
/v2/products/7  → "price":{"amount":4500,...}

যোগ করে বদলানো আর সহনশীল পাঠক

ঘর যোগ নিরাপদ হয় একটি শর্তে: client-কেও নিয়ম মানতে হবে। এই নিয়মের নাম tolerant reader, অর্থাৎ যা লাগে শুধু তা পড়ুন, বাকিটা উপেক্ষা করুন, আর যা পড়লেন তা যাচাই করুন। উল্টো দিকে “কঠোর client” চেনা ঘরের বাইরে কিছু দেখলেই থেমে যায়। নিচের কোডে তিন রকম উত্তর দুই client-কে দেওয়া হয়েছে। চালিয়ে দেখুন।

// আগের উত্তর, ঘর যোগের পরের উত্তর, আর ঘরের অর্থ বদলের পরের উত্তর
const before = '{"id":7,"name":"Morich","price":45}';
const added  = '{"id":7,"name":"Morich","price":45,"unit":"kg"}';
const broken = '{"id":7,"name":"Morich","price":{"amount":4500}}';

// কঠোর client: চেনা ঘরের বাইরে কিছু দেখলেই থেমে যায়
function strictClient(text) {
  const body = JSON.parse(text);
  for (const key of Object.keys(body)) {
    if (!['id', 'name', 'price'].includes(key)) {
      throw new Error(`unknown field: ${key}`);
    }
  }
  return `${body.name}: ${body.price} taka`;
}

// সহনশীল client: যা লাগে শুধু তা পড়ে, আর সেটুকু যাচাই করে
function tolerantClient(text) {
  const { name, price } = JSON.parse(text);
  if (typeof price !== 'number') throw new Error('price is not a number');
  return `${name}: ${price} taka`;
}

for (const [label, text] of [['before', before], ['added ', added], ['broken', broken]]) {
  for (const [who, read] of [['strict  ', strictClient], ['tolerant', tolerantClient]]) {
    try {
      console.log(label, who, 'OK  ', read(text));
    } catch (e) {
      console.log(label, who, 'FAIL', e.message);
    }
  }
}

৩ · Version কোথায় লিখবেন: চার ধরন

ভাঙা বদল এড়ানো না গেলে client-কে বলতে হবে সে কোন চুক্তি চায়। এই “কোথায় বলবে” প্রশ্নের চারটি প্রচলিত উত্তর আছে। কোনোটি সব জায়গায় সেরা নয়, আর এই নিয়ে সমাজে মতভেদ আছে।

তারিখ-ভিত্তিক versioning-এর পরিচিত প্রকাশ্য বিবরণ আছে Stripe-এর ২০১৭ সালের প্রকৌশল-লেখায়। সেখানে তারা জানায়, প্রতিটি account একটি তারিখে আটকে থাকে, আর ভেতরে রূপান্তরের ধাপ দিয়ে পুরোনো চেহারা বানানো হয়। বড় দলের জন্য এটি শক্তিশালী, কিন্তু সেই যন্ত্রপাতি বানানো ও রক্ষা করা নিজেই একটি প্রকল্প।

একটি ফাঁদও জেনে রাখুন। Header-ভিত্তিক version-এ একই URL দুই রকম উত্তর দেয়। CDN যদি শুধু URL দেখে cache করে, v1-এর client v2-র উত্তর পেতে পারে। তাই response-এ Vary: Api-Version দিতে হয়। URL versioning-এ এই সমস্যা জন্মায়ই না।

৪ · Express-এ /v1 আর /v2, service একটিই

সবচেয়ে সাধারণ ভুল হলো পুরো ফোল্ডার কপি করা: routes-v2/, services-v2/. এতে একটি bug ঠিক করতে দুই জায়গায় হাত দিতে হয়, আর কিছুদিন পরে দুই কপির নিয়ম আলাদা হয়ে যায়। ছাড়ের হিসাব v1-এ এক, v2-তে আরেক। মনে রাখুন, version আলাদা হয় চুক্তিতে, ব্যবসার নিয়মে নয়।

আগে Node-এর নিজের http module-এ ধারণাটি দেখি। এখানে কোনো framework নেই, তাই সব কিছু চোখের সামনে।

const http = require('node:http');

// একটিমাত্র service: দাম সব সময় পয়সায়
const service = {
  get: (id) => (id === 7 ? { id, name: 'Morich', poisha: 4500, stock: 12 } : null),
};

// প্রতিটি version শুধু উত্তরের চেহারা ঠিক করে
const present = {
  v1: (p) => ({ id: p.id, name: p.name, price: p.poisha / 100 }),
  v2: (p) => ({ id: p.id, name: p.name,
    price: { amount: p.poisha, currency: 'BDT' }, inStock: p.stock > 0 }),
};

const server = http.createServer((req, res) => {
  const m = req.url.match(/^\/(v1|v2)\/products\/(\d+)$/);
  const product = m && service.get(Number(m[2]));
  if (!product) {
    res.writeHead(404);
    return res.end();
  }
  res.writeHead(200, { 'content-type': 'application/json' });
  res.end(JSON.stringify(present[m[1]](product)));
});

server.listen(0, '127.0.0.1', async () => {
  const base = `http://127.0.0.1:${server.address().port}`;
  for (const path of ['/v1/products/7', '/v2/products/7', '/v3/products/7']) {
    const res = await fetch(base + path);
    console.log(path, res.status, await res.text());
  }
  server.close();
});

এবার আসল Express. পর্ব ২৫-এর express.Router একটি factory function থেকে বানালে দুই version একই route পায়, শুধু presenter আলাদা। নিচের কোড সত্যিকারের project থেকে নেওয়া, ছোট করে দেখানো হলো। সত্যিকারের run. লেখার সময়ের সংস্করণ: Node 24.15.0, Express 5.3.0, Zod 4.6.7, TypeScript 5.9.3, tsx 4.23.15.

const toV1 = (r: Row) => ({ id: r.id, name: r.name, price: r.pricePoisha / 100 });
const toV2 = (r: Row) => ({
  id: r.id, name: r.name,
  price: { amount: r.pricePoisha, currency: 'BDT' as const },
  inStock: r.stock > 0,
});

function productRouter(present: (r: Row) => unknown) {
  const router = Router();
  router.get('/products/:id', async (req, res) => {
    const { id } = ProductParams.parse(req.params);
    const row = await svc.get(id);
    if (!row) {
      res.status(404).type('application/problem+json').json({
        type: 'about:blank', title: 'Not Found', status: 404,
        detail: `পণ্য ${id} পাওয়া যায়নি`,
      });
      return;
    }
    res.json(present(row));
  });
  return router;
}

app.use('/v1', deprecated, productRouter(toV1));
app.use('/v2', productRouter(toV2));

deprecated middleware পরের অংশে দেখবেন। শুধু /v1-এর সামনে বসানোয় v2 এর খরচ দেয় না। দুই version-এর সত্যিকারের উত্তর:

$ curl -si -H 'X-Client-Id: android-3.2.0' http://127.0.0.1:3935/v1/products/7
HTTP/1.1 200 OK
X-Powered-By: Express
Deprecation: @1793491200
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://bazarghar.example/migrate-v2>; rel="deprecation"; type="text/html"
Content-Type: application/json; charset=utf-8
Content-Length: 83
…
{"id":7,"name":"কাঁচা মরিচ ২৫০ গ্রাম","price":45}

$ curl -si http://127.0.0.1:3935/v2/products/7
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
…
{"id":7,"name":"কাঁচা মরিচ ২৫০ গ্রাম","price":{"amount":4500,"currency":"BDT"},"inStock":true}

৫ · পুরোনো version-কে অবসর দেওয়া

দুই version চিরকাল চালানো যায় না। প্রতিটি bug fix, প্রতিটি নতুন নিয়ম দুই presenter-এর সঙ্গে মেলাতে হয়। ৩টি version আর ২৪টি endpoint মানে ৭২টি জোড়া পরীক্ষা করা। আবার হঠাৎ বন্ধ করলে রহিমা চাচির অ্যাপ মরে যায়। মাঝের পথটির নাম deprecation: আগে থেকে জানানো, মাপা, তারপর বন্ধ করা।

HTTP-তে এর জন্য দুটি মানসম্মত header আছে, আর দুটির তারিখের ধরন আলাদা:

RFC 9745 বলে, Sunset-এর সময় Deprecation-এর সময়ের আগে হতে পারবে না। আর দুই RFC-ই পরিষ্কার: এই header জানানোর জন্য, বন্ধ করার যন্ত্র নয়। Middleware-টি ছোট:

const DEPRECATED_AT = Date.UTC(2026, 10, 1);      // 2026-11-01
const SUNSET_AT = Date.UTC(2027, 4, 1);           // 2027-05-01

export const deprecated: RequestHandler = (req, res, next) => {
  res.set('Deprecation', `@${DEPRECATED_AT / 1000}`);
  res.set('Sunset', new Date(SUNSET_AT).toUTCString());
  res.set('Link', '<https://bazarghar.example/migrate-v2>; rel="deprecation"; type="text/html"');
  res.on('finish', () => {
    console.log(JSON.stringify({
      msg: 'deprecated_call',
      path: req.path,
      status: res.statusCode,
      client: req.get('x-client-id') ?? 'unknown',
      ua: req.get('user-agent') ?? 'unknown',
    }));
  });
  next();
};

Header পাঠালেই কাজ শেষ নয়। Client-কে সেটি পড়তেও হবে, নইলে কেউ জানবে না। আপনার নিজের অ্যাপে একটি ছোট পাঠক রাখুন, যা error log-এ একবার সতর্ক করে। নিচে নকল ঘড়ি দিয়ে সেটি চলছে।

const http = require('node:http');
const server = http.createServer((req, res) => {
  res.writeHead(200, {
    'content-type': 'application/json',
    Deprecation: '@1793491200',
    Sunset: 'Sat, 01 May 2027 00:00:00 GMT',
    Link: '<https://bazarghar.example/migrate-v2>; rel="deprecation"',
  });
  res.end('{"id":7}');
});
const warned = new Set();                       // একই path-এ একবারই সতর্কতা
const DAY = 24 * 60 * 60 * 1000;

function checkRetirement(path, headers, now) {
  const dep = headers.get('deprecation');
  if (!dep || warned.has(path)) return;
  warned.add(path);
  const deprecatedAt = Number(dep.slice(1)) * 1000;   // '@' বাদ, সেকেন্ড থেকে ms
  const sunsetAt = Date.parse(headers.get('sunset'));
  console.log('deprecated on', new Date(deprecatedAt).toISOString().slice(0, 10));
  console.log('sunset on    ', new Date(sunsetAt).toISOString().slice(0, 10));
  console.log('days left    ', Math.round((sunsetAt - now) / DAY));
  console.log('guide        ', headers.get('link'));
}

server.listen(0, '127.0.0.1', async () => {
  const url = `http://127.0.0.1:${server.address().port}/v1/products/7`;
  const today = Date.UTC(2027, 0, 30);          // নকল ঘড়ি: ৩০ জানুয়ারি ২০২৭
  for (let i = 0; i < 3; i++) {
    const res = await fetch(url);
    checkRetirement('/v1/products/7', res.headers, today);
    console.log('call', i + 1, res.status, await res.text());
  }
  server.close();
});

কে এখনও ডাকছে, মেপে দেখুন

তারিখ ঠিক করা সহজ, সিদ্ধান্ত নেওয়া কঠিন। উত্তর আসে পর্ব ৩১-এর structured logging থেকে। উপরের middleware প্রতিটি পুরোনো call-এ একটি JSON লাইন লেখে। নিজের অ্যাপে X-Client-Id header বসিয়ে রাখলে এক লাইনের হিসাবেই নাম বেরিয়ে আসে। সত্যিকারের run, সাতটি পরীক্ষার call:

$ node count.mjs out/server.log
   4 android-3.2.0
   1 ios-2.1.0
   1 partner-dokan
   1 unknown

unknown সারিটিই সবচেয়ে দামি। এটি বলে, এমন কেউ ডাকছে যাকে আপনি চেনেন না, তাই ইমেইলও করতে পারবেন না। User-Agent, API key বা rate limit-এর হিসাব মিলিয়ে তাকে খুঁজতে হয়।

কত সপ্তাহে ট্রাফিক নামবে: একটি হিসাব

ধরুন (অনুমিত সংখ্যা) প্রথম সপ্তাহে v1-এ 100000 call, আর প্রতি সপ্তাহে ২৫% কমে। কত সপ্তাহে 1000-এর নিচে নামবে?

calls(n) = 100000 × 0.75^n
100000 × 0.75^n < 1000
0.75^n < 0.01
n > ln(0.01) / ln(0.75) = 16.008
সপ্তাহ 16: 1002   (এখনও বেশি)
সপ্তাহ 17:  752   (নিচে নেমেছে)

উত্তর ১৭ সপ্তাহ। গুণিতক হারে কমা ট্রাফিকে শেষের অংশটুকুই সবচেয়ে ধীর: প্রথম ৪ সপ্তাহে ৬৮% কমে যায়, কিন্তু ১%-এ নামতে মোট চারগুণ সময় লাগে। পুরো অবসরটি নিচের ধাপে দেখুন। সংখ্যাগুলো এই একই অনুমিত সূত্রের।

৬ · OpenAPI: চুক্তিকে যন্ত্রে পড়ার মতো করে লেখা

এতক্ষণ চুক্তি ছিল মানুষের মাথায় আর একটি wiki পাতায়। OpenAPI হলো HTTP API-র চুক্তি লেখার একটি মানসম্মত ভাষা, YAML বা JSON-এ। একবার লেখা থাকলে মানুষও পড়তে পারে, যন্ত্রও: docs, client, lint, পরীক্ষা, সব একই ফাইল থেকে আসে।

এই পর্বের document 3.1.1, কারণ zod-openapi 6.0.2-এর README শুধু 3.1.0 আর 3.1.1 সমর্থনের কথা বলে। নতুন spec বেরোলেই সব টুল তা ধরতে পারে না, তাই version বাছুন আপনার টুলের সবচেয়ে দুর্বল সদস্য দেখে। আমাদের run-এ Spectral, Redocly, oasdiff আর openapi-typescript openapi: 3.2.0 লেখা ফাইল পড়তে আপত্তি করেনি, তবে আমরা 3.2-এর নতুন কোনো সুবিধা পরীক্ষা করিনি।

Document-এর শীর্ষে চারটি অংশ মনে রাখলেই চলে:

বাজারঘরের সত্যিকারের ফাইল থেকে একটি অংশ। পুরো ফাইলটি ১৯১ লাইন, আর Redocly ও Spectral-এ কোনো error ছাড়াই পাস করেছে।

openapi: 3.1.1
info:
  title: বাজারঘর API
  version: 2.0.0
servers:
  - url: https://api.bazarghar.example/v2
security: []
paths:
  /products/{id}:
    get:
      operationId: getProduct
      summary: একটি পণ্য
      tags:
        - products
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
            exclusiveMinimum: 0
      responses:
        "200":
          description: পাওয়া গেছে
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductV2"
              examples:
                chili:
                  summary: মজুত আছে এমন পণ্য
                  value:
                    id: 7
                    name: কাঁচা মরিচ ২৫০ গ্রাম
                    price:
                      amount: 4500
                      currency: BDT
                    inStock: true
        "404":
          description: এই id-র পণ্য নেই
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

লক্ষ্য করুন, 404-এর জন্যও আলাদা schema আছে। Error চুক্তির অংশ। application/problem+json হলো পর্ব ৩৩-এর problem details ধরন। আর security: [] মানে এই API-র কাজগুলোতে সাধারণভাবে login লাগে না; /me/orders নিজের security দিয়ে bearer token চায়।

আগে নকশা, নাকি আগে কোড

মূল কথা, সত্যের উৎস একটিই রাখুন। দুই জায়গায় হাতে লেখা চুক্তি একসময় আলাদা হবেই। বাজারঘরের দল Express আর Zod আগেই ব্যবহার করছে, তাই তারা code-first. কিন্তু document-এর বদল pull request-এ পড়ে দেখা হয়, যাতে নকশা-পর্যালোচনাও থাকে।

৭ · Zod থেকে document, Express থেকে docs

আপনার কাছে পর্ব ২৭-এর Zod schema আগে থেকেই আছে। সেগুলোই request যাচাই করে, TypeScript type দেয়। Document-ও তা থেকে এলে তিনটি জিনিস এক উৎসে থাকে। Zod 4-এর জন্য দুটি পরিচিত package আছে, আর লেখার সময়ে দুটিরই peerDependencies-এ zod ^4.0.0: zod-openapi (6.0.2) আর @asteasolutions/zod-to-openapi (9.1.0). আমরা প্রথমটি চালিয়েছি, দ্বিতীয়টি চালাইনি। Zod 4-এর .meta()-তে id দিলে schema components-এ যায়।

export const Money = z.object({
  amount: z.number().int().nonnegative()
    .meta({ description: 'পয়সায় দাম', examples: [4500] }),
  currency: z.literal('BDT'),
}).meta({ id: 'Money' });

export const ProductV2 = z.object({
  id: z.number().int().positive().meta({ examples: [7] }),
  name: z.string().min(1).max(120).meta({ examples: ['কাঁচা মরিচ ২৫০ গ্রাম'] }),
  price: Money,
  inStock: z.boolean().meta({ examples: [true] }),
}).meta({ id: 'ProductV2' });

import { createDocument } from 'zod-openapi';

export const doc = createDocument({
  openapi: '3.1.1',
  info: { title: 'বাজারঘর API', version: '2.0.0' },
  paths: {
    '/products/{id}': {
      get: {
        operationId: 'getProduct',
        requestParams: { path: ProductParams },
        responses: {
          '200': {
            description: 'পাওয়া গেছে',
            content: { 'application/json': { schema: ProductV2 } },
          },
          '404': problem('এই id-র পণ্য নেই'),
        },
      },
    },
  },
});

সত্যিকারের run-এ npx tsx src/openapi.ts ছাপল wrote out/v1.openapi.yaml, out/v2.openapi.yaml. তৈরি ফাইলে দুটি জিনিস চোখে পড়ল, যা তুলে ধরা দরকার।

• Response schema-য় additionalProperties: false বসেছে। কাগজে এটি বলছে “এর বাইরে আর কোনো ঘর আসবে না”, অথচ আমরা চাই client সহনশীল হোক আর নতুন ঘর যোগ করা নিরাপদ থাকুক। পরীক্ষায় দেখা গেল, response-এ z.object দেয় additionalProperties: false, আর z.looseObject দেয় additionalProperties: {}. Request body-র z.object-এ এই লাইনটি আসেনি। Document থেকে কোনো কঠোর client যাচাই বানালে এই লাইনটি আগে পড়ে নিন।
• maximum: 9007199254740991 এসেছে। এটি .int()-এর নিরাপদ সীমা, ক্ষতি নেই, তবে পড়তে কিছুটা অস্বস্তিকর।

এবার মানুষের জন্য পাতা। পর্ব ২৬-এর মতো এগুলোও সাধারণ middleware.

import swaggerUi from 'swagger-ui-express';
import { apiReference } from '@scalar/express-api-reference';

const v2Doc = buildDoc('v2');
app.get('/openapi.json', (_req, res) => { res.json(v2Doc); });
app.use('/docs', swaggerUi.serve, swaggerUi.setup(v2Doc));
app.use('/reference', apiReference({ url: '/openapi.json' }));

$ curl -s -o /dev/null -w "%{http_code} %{content_type}\n" http://127.0.0.1:3935/docs/
200 text/html; charset=utf-8
$ curl -s -o /dev/null -w "%{http_code} %{content_type}\n" http://127.0.0.1:3935/reference
200 text/html; charset=utf-8
$ curl -s http://127.0.0.1:3935/docs/ | grep -o 'src="[^"]*"'
src="./swagger-ui-bundle.js"
src="./swagger-ui-standalone-preset.js"
src="./swagger-ui-init.js"
$ curl -s http://127.0.0.1:3935/reference | grep -o 'https://[^"]*'
https://cdn.jsdelivr.net/npm/@scalar/api-reference/esm.js'

দুটি পাতাই Edge browser-এ খুলে দেখা হয়েছে। Swagger UI দেখাল বাজারঘর API, 2.0.0, OAS 3.1, Authorize বোতাম আর operation-এর তালিকা। Scalar-ও একই document দেখাল। শেষের আউটপুটটি একটি সত্যিকারের পার্থক্য দেখায়: Swagger UI-র ফাইল আপনার server থেকেই আসে, আর Scalar-এর এই package-এর পাতা একটি CDN থেকে JavaScript আনে। অভ্যন্তরীণ নেটওয়ার্কে বা কড়া CSP-তে এই পার্থক্য গুরুত্বপূর্ণ।

৮ · যন্ত্রকে পাহারায় বসানো: lint আর ভাঙন ধরা

লিখিত চুক্তির সবচেয়ে বড় লাভ, যন্ত্র সেটি পড়তে পারে। Linter দেখে document নিজে ভালো কি না। Diff টুল দেখে দুই document-এর মধ্যে কী ভেঙেছে। ইচ্ছা করে একটি খারাপ খসড়া লিখলাম, একটি $ref-এ বানান ভুল (Prodcut), {id} ঘোষণা নেই, example-এর type ভুল। Spectral 6.17.0-এর ruleset spectral:oas, সঙ্গে আমাদের নিজের একটি নিয়ম: 4xx-এর উত্তর application/problem+json হতে হবে।

extends: ["spectral:oas"]
rules:
  operation-description: error
  bazarghar-error-has-problem-json:
    description: 4xx response must use application/problem+json
    message: "{{path}} must describe application/problem+json"
    severity: error
    given: "$.paths[*][*].responses[?(@property >= '400' && @property < '500')].content"
    then:
      field: application/problem+json
      function: truthy

$ npx spectral lint out/draft.openapi.yaml

~/bazarghar/out/draft.openapi.yaml
  1:1   warning  oas3-api-servers           OpenAPI "servers" must be present and non-empty array.
  2:6   warning  info-contact               Info object must have "contact" object.
  2:6   warning  info-description           Info "description" must be present and non-empty string.
  7:9     error  operation-description      Operation "description" must be present and non-empty string.
  7:9   warning  operation-operationId      Operation must have "operationId".
  7:9   warning  operation-tags             Operation must have non-empty "tags" array.
  7:9     error  path-params                Operation must define parameter "{id}" as expected by path "/products/{id}".
 15:23    error  invalid-ref                '#/components/schemas/Prodcut' does not exist
 18:19    error  bazarghar-error-has-problem-json  … must describe application/problem+json
 24:13  warning  oas3-unused-component      Potentially unused component has been detected.
 28:42    error  oas3-valid-schema-example  "example" property type must be integer

✖ 11 problems (5 errors, 6 warnings, 0 infos, 0 hints)

Spectral বানান ভুলের জন্য Product-কে “অব্যবহৃত” বলেও ধরল: একটি ভুল থেকে দুটি বার্তা। Redocly CLI 2.72.1 একই ফাইলে ৪টি error আর ৪টি warning দিল, আর দৃষ্টিভঙ্গি একটু আলাদা। তার একটি error হলো security-defined: Every operation should have security defined on it or on the root level. আমাদের প্রথম ভালো document-ও এখানে আটকেছিল। পণ্য দেখতে login লাগে না, তাই root-এ security: [] লিখে সিদ্ধান্তটি প্রকাশ্য করা হলো। এই নিয়মটি শিক্ষণীয়: টুল আপনাকে login দিতে বলে না, শুধু “ভুলে গেছেন, না ইচ্ছা করে?” প্রশ্নটি তোলে।

$ npx redocly lint out/v1.openapi.yaml out/v2.openapi.yaml
…
Woohoo! Your API descriptions are valid. 🎉

দুই document মেলানো

Lint একটি ফাইল দেখে, তাই সে জানে না গতকাল কী ছিল। ভাঙা বদল ধরতে দরকার দুই ফাইল মেলানো। oasdiff (1.35.0) একটি Go প্রোগ্রাম, GitHub release থেকে নামিয়ে checksum মিলিয়ে চালালাম। npm-এ oasdiff নামে যা আছে তা এই টুল নয়, সেটি 0.0.1-security নামের একটি ফাঁকা নিরাপত্তা-স্থানধারক। ভিন্ন তিনটি বদলের সত্যিকারের ফল:

$ oasdiff breaking out/v1.openapi.yaml out/v1-add.yaml --fail-on ERR
No breaking changes to report, but the specs are different.
Run 'oasdiff diff' to see structural differences.
exit=0

$ oasdiff breaking out/v1.openapi.yaml out/v1-rename.yaml --fail-on ERR
2 changes: 2 error, 0 warning, 0 info
error  [response-required-property-removed] at out/v1-rename.yaml
  in API GET /products
    removed the required property `items/name` from the response with the `200` status
…
exit=1

$ oasdiff breaking out/v1.openapi.yaml out/v1-param.yaml --fail-on ERR
1 changes: 1 error, 0 warning, 0 info
error  [new-required-request-parameter] at out/v1-param.yaml
  in API GET /products
    added the new required `query` request parameter `shop`
exit=1

একটি ছোট কিন্তু দামি তথ্য: --fail-on ERR ছাড়া আমাদের run-এ ৬টি error থাকার পরেও exit code ছিল 0. CI-তে flag না দিলে পাহারাদার চিৎকার করবে, কিন্তু দরজা খোলা থাকবে। পর্ব ০৫-এ দেখা npm script-এর মতো এটিকেও pipeline-এর ধাপ বানান, পর্ব ৮১-তে CI আসবে। ধারণাটি পরিষ্কার করতে এবার একই কাজের একটি খুব ছোট শিক্ষামূলক মডেল চালান। এটি oasdiff নয়, শুধু যুক্তিটি।

// দুই schema মেলানোর শিক্ষামূলক মডেল। side: 'response' বা 'request'
function diff(a, b, side) {
  const out = [];
  const req = (s, k) => s.required.includes(k);
  for (const k of Object.keys(a.properties)) {
    const was = a.properties[k], now = b.properties[k];
    if (!now) out.push(`BREAKING removed ${k}`);
    else if (was.type !== now.type) out.push(`BREAKING type ${k}: ${was.type} -> ${now.type}`);
    else if (side === 'response' && req(a, k) && !req(b, k)) out.push(`BREAKING ${k} no longer always sent`);
    else if (side === 'request' && !req(a, k) && req(b, k)) out.push(`BREAKING ${k} now required`);
  }
  for (const k of Object.keys(b.properties)) {
    if (a.properties[k]) continue;
    if (side === 'request' && req(b, k)) out.push(`BREAKING new required ${k}`);
    else out.push(`ok added ${k}`);
  }
  return out.length ? out : ['safe'];
}

const str = { type: 'string' }, int = { type: 'integer' };
const v1 = { properties: { id: int, name: str, price: int }, required: ['id', 'name', 'price'] };

const cases = {
  'add optional field':  { properties: { ...v1.properties, unit: str }, required: v1.required },
  'rename name -> title': { properties: { id: int, title: str, price: int }, required: ['id', 'title', 'price'] },
  'price becomes string': { properties: { ...v1.properties, price: str }, required: v1.required },
  'name now optional':   { properties: v1.properties, required: ['id', 'price'] },
};
for (const [label, v2] of Object.entries(cases)) {
  console.log(label);
  console.log('  response:', diff(v1, v2, 'response').join('; '));
  console.log('  request: ', diff(v1, v2, 'request').join('; '));
}

৯ · Typed client আর এমন docs, যা মানুষ পড়ে

Backend আর frontend আলাদা repository-তে থাকলে ভাগ করা type (পর্ব ০৬) সরাসরি import করা যায় না। OpenAPI সেখানে সেতু। openapi-typescript document থেকে TypeScript type বানায়, আর openapi-fetch সেই type দিয়ে একটি পাতলা client দেয়। এর জন্য চলার সময়ে client-কে document পড়তে হয় না।

$ npx openapi-typescript out/v2.openapi.yaml -o client/bazarghar.d.ts
✨ openapi-typescript 7.13.0
🚀 out/v2.openapi.yaml → client/bazarghar.d.ts [24.6ms]

লক্ষ্য করুন, লেখার সময়ে openapi-typescript 7.13.0-এর peer হলো typescript ^5.x. তাই এই project-এ TypeScript 5.9.3 রাখা হয়েছে; 6.0 দিয়ে npm ERESOLVE দিয়েছে। পুরোনো অ্যাপের মতো ভুল কোড লিখলে compiler সঙ্গে সঙ্গে ধরে:

const api = createClient<paths>({ baseUrl: 'http://127.0.0.1:3935/v2' });
const { data } = await api.GET('/products/{id}', { params: { path: { id: '7' } } });
const taka: number = data!.price;
console.log(taka.toFixed(2));
await api.GET('/product/{id}');

$ npx tsc --noEmit
client/old.ts(5,70): error TS2322: Type 'string' is not assignable to type 'number'.
client/old.ts(6,7): error TS2322: Type '{ amount: number; currency: "BDT"; }' is not assignable to type 'number'.
client/old.ts(8,11): error TS2554: Expected 2 arguments, but got 1.

আর ঠিক কোডটি চলন্ত server-এর বিরুদ্ধে সত্যিকারের ফল দিল। data আর error আলাদা বলে 404-এর detail-ও type-সহ আসে:

$ npx tsx client/app.ts
200 4500 undefined
404 পণ্য 99 পাওয়া যায়নি

পুরো পথটি এখন এক সুতোয় বাঁধা। একটি schema থেকে শুরু করে শেষ পর্যন্ত যান:

Money = z.object({
  amount: z.number().int().nonnegative(),
  currency: z.literal('BDT'),
}).meta({ id: 'Money' })

Money:
  type: object
  properties:
    amount:
      type: integer
      minimum: 0
      …
    currency:
      type: string
      const: BDT

$ npx spectral lint out/v2.openapi.yaml
No results with a severity of 'error' found!

$ oasdiff breaking v1 v2 --fail-on ERR
6 changes: 6 error, 0 warning, 0 info
exit=1

বাজারঘর API  2.0.0  OAS 3.1
[Authorize]
GET  /products
GET  /products/{id}
GET  /me/orders

Money: {
  /** @description পয়সায় দাম */
  amount: number;
  /** @constant */
  currency: "BDT";
};

যে docs মানুষ সত্যিই ব্যবহার করে

তৈরি পাতা মানেই ভালো docs নয়। Schema বলে কী সম্ভব, docs বলে কীভাবে কাজ হবে। পাঁচটি জিনিস যোগ করুন:

• প্রথম পাঁচ মিনিট: একটি কপি করা যায় এমন curl আর তার সত্যিকারের উত্তর
• Auth: token কোথা থেকে আসে, কোন header-এ যায়, মেয়াদ কত, ভুল হলে কী আসে
• Error: প্রতিটি status-এর একটি example আর “কী করবেন”, শুধু “400 Bad Request” নয়
• Example: বাস্তব মান, string বা foo নয়; প্রতিটি example schema-র সঙ্গে lint-এ মিলিয়ে নেওয়া
• Changelog আর migration গাইড: কী বদলেছে, কবে, আর আগের কোড কীভাবে বদলাবেন

১০ · AI-এর যুগে API-র চুক্তি

AI এক মিনিটে YAML আর route লিখে দেয়। সমস্যা হলো, চুক্তি ভাঙলে কোনো লাল দাগ পড়ে না। কোড চলে, test সবুজ, ভাঙে অন্য কারও ফোন। তাই এই বিষয়ে AI-র কাজ যাচাই করা বাড়তি জরুরি।

• AI-র document Spectral বা Redocly-তে চালিয়েছি, আর সব warning পড়েছি
• আগের document-এর সঙ্গে oasdiff মিলিয়েছি, exit code দেখেছি
• অর্থ বা একক বদলেছে কি না নিজে পড়ে দেখেছি, কারণ যন্ত্র এটি ধরে না
• প্রতিটি নতুন package-এর নাম, version আর Zod বা TypeScript সমর্থন যাচাই করেছি
• আসল server চালিয়ে response-এর সঙ্গে document মিলিয়েছি
• Example-এ কোনো আসল token, ইমেইল বা গোপন মান নেই