কেন আপনার API JSON স্কিমা ছাড়া ‘ডিজাইন দ্বারা ভাঙা’ হয়

লোকেরা যুক্তি দিতে পারে যে JSON স্কিমা ওভারকিল বা পুরানো। কিন্তু এই নিবন্ধে, আমরা অন্বেষণ করব যে এটি এমন নয় এবং কীভাবে এটি প্রায়শই উপেক্ষা করা হয় তা বুঝতে পারি।

প্রথমে, আমাকে শুনুন — আপনি ইতিমধ্যে একটি স্কিমা ব্যবহার করছেন৷

এটি সম্পর্কে চিন্তা করুন: আপনার শেষ ব্যবহারকারীরা যদি API ভোক্তা হন, তারা বাহ্যিক (চিন্তা করুন র‍্যাপিড API) বা আপনার (মাইক্রো?) পরিষেবার API ব্যবহার করে অভ্যন্তরীণ টিমমেটই হোক না কেন, প্রতিবার যখন তারা একটি এন্ডপয়েন্টে আঘাত করে তখন তারা একটি নির্দিষ্ট উপায় দেখার জন্য প্রতিক্রিয়াগুলির উপর নির্ভর করে। তারা বিস্ময়ের আশা করছেন না; তারা ধারাবাহিকতা আশা করছে। সেই ধারাবাহিকতা? এটা একটা স্কিমা। আপনি মূলত একটি অন্তর্নিহিত স্কিমা সব বরাবর ব্যবহার করা হয়েছে; আপনি এখনও এটি আনুষ্ঠানিক করেননি।

আপনি যদি এখনও আমার সাথে থাকেন তবে আসুন একটি JSON স্কিমা থাকার সুবিধাগুলি নিয়ে আলোচনা করি৷

• ডেটা যাচাই করে: এটি আপনার এপিআইকে গোলমাল করার আগে সমস্যাগুলি (যেমন অবৈধ ইমেল বা নেতিবাচক বয়স) ধরে। এছাড়াও, সর্বোত্তম অংশটি হল, বেশিরভাগ প্রোগ্রামিং ভাষায় JSON স্কিমার জন্য বৈধতা লাইব্রেরি রয়েছে।
• নথি আপনার API: JSON স্কিমা মূলত স্ব-ডকুমেন্টিং, তাই অন্য ডেভেলপাররা দেখতে পারে যে তাদের ঠিক কোন ডেটা পাঠাতে হবে। কোন অনুমান!
• আপনার API সামঞ্জস্যপূর্ণ রাখে: যখন প্রতিটি অনুরোধ এবং প্রতিক্রিয়া একই কাঠামো অনুসরণ করে, তখন আপনি সেই হতাশাজনক এড়িয়ে যান “অপেক্ষা করুন, এই ক্ষেত্রটি কী ফর্ম্যাট হওয়ার কথা ছিল?” মুহূর্ত
• সময় বাঁচায়: অনেক টুল এমনকি JSON স্কিমার উপর ভিত্তি করে কোড এবং ডকুমেন্টেশন স্বয়ংক্রিয়ভাবে তৈরি করতে পারে, তাই আপনি অনেক ক্লান্তিকর সেটআপ এড়িয়ে যেতে পারেন।

এক মিনিট অপেক্ষা করুন! আপনি কি জানেন JSON স্কিমা কি?

আমরা এই নিবন্ধে গভীরভাবে ডুব দেওয়ার আগে, আসুন জেনে নেওয়া যাক JSON স্কিমা কী। আপনি যদি একজন ডেভেলপার হন এবং JSON স্কিমার কথা না শুনে থাকেন, তাহলে ঠিক আছে! সত্যি বলতে, আমি আমার কোডিং জীবনের প্রথম কয়েক বছর আপনার সাথেই ছিলাম, আনন্দিতভাবে অজানা।

যাইহোক, JSON স্কিমা কি?

আমি নিশ্চিত আপনি ইতিমধ্যেই ভাবছেন, “ওহ দুর্দান্ত, আমার প্রতিক্রিয়া ডেটাতে টাইপের ওভারলোডের আরেকটি স্তর চাপা পড়েছে।” আর সততার সাথে? আপনি সম্পূর্ণ ভুল না! এটা প্রথম নজরে যে মত দেখতে পারে. কিন্তু এর একটি ঘনিষ্ঠভাবে তাকান এবং কর্ম এটি দেখুন.

কল্পনা করুন আপনি মাত্র তিনটি ক্ষেত্র সহ একটি ব্যবহারকারী নিবন্ধন ফর্ম সেট আপ করছেন:

1. নাম: 2 থেকে 50 অক্ষর দীর্ঘ যে কোন জায়গায় একটি স্ট্রিং হতে হবে।
2. ইমেইল: আচ্ছা, এটা একটা ইমেইল হতে হবে। দুহ!
3. বয়স: শুধুমাত্র 18 এবং তার বেশি বয়সী ব্যবহারকারীরাই নিবন্ধন করতে পারবেন।

{
  "name": "John",
  "email": "(email protected)",
  "age": 25
}

ওহ, এবং সব তিনটি ক্ষেত্র হয় প্রয়োজনীয়. এই স্কিমাটি কীভাবে গঠন করবে তা এখানে:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User Registration",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 50
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 18
    }
  },
  "required": ("name", "email", "age")
}

সম্ভবত এটি শুরুতে ভীতিকর দেখায়। কিন্তু একই সময়ে, এটা বোঝা যায়, তাই না?

আসুন এটি ভেঙে ফেলি এবং প্রতিটি অংশ কী করছে তা বুঝতে পারি।

• $schema: এটি আপনাকে JSON স্কিমার কোন সংস্করণ ব্যবহার করছে তা আপনাকে বলে। (পরবর্তী সংস্করণগুলিতে আরও।)
• title: এটা একটা লেবেলের মত। এখানে, এটি “ব্যবহারকারী নিবন্ধন।” এটি প্রযুক্তিগত কিছু করে না, তবে আপনার স্কিমার জন্য একটি নাম থাকা ভাল।
• type: আপনি কোন ধরণের ডেটা নিয়ে কাজ করছেন তা এখানে আপনি নির্ধারণ করেন। বেশিরভাগ API ব্যবহার করে object (যেহেতু এটি স্ট্রাকচার্ড ডেটা), তবে JSON স্কিমা অ্যারে, স্ট্রিং, সংখ্যা এবং আরও অনেক কিছু পরিচালনা করতে পারে।
• properties: এখানেই যাদু ঘটে। এটি যেখানে আপনি আপনার বস্তুর প্রতিটি ক্ষেত্রের জন্য নিয়ম লেখেন।
• required: এটি এমন ক্ষেত্রগুলির একটি তালিকা যা অবশ্যই অন্তর্ভুক্ত করতে হবে, ব্যতিক্রম নেই।

ঠিক আছে, অপেক্ষা করুন! এটি এখনও আরেকটি “কিভাবে JSON স্কিমা” টিউটোরিয়াল হতে যাচ্ছে না। JSON স্কিমা কী এবং কীভাবে এটি ব্যবহার করা যায় সেই একই পুরানো স্পিলের জন্য আমরা এখানে নেই। এর জন্য ইতিমধ্যেই প্রচুর ব্লগ, ভিডিও এবং টিউটোরিয়াল রয়েছে। সুতরাং, আপনার নিজের গবেষণা করুন, এবং আসুন অপ্রয়োজনীয়তা এড়িয়ে যাই, আমরা কি করব?

এটি আপনার হোমওয়ার্ক হতে পারে:
1. সীমাবদ্ধতা এবং বৈধতা নিয়ম অন্বেষণ করুন
2. উন্নত JSON স্কিমা বৈশিষ্ট্যগুলি অন্বেষণ করুন (oneOf, anyOf, এবং allOf)
3. আপনার API অনুরোধগুলিতে JSON স্কিমা প্রয়োগ করুন৷
4. JSON স্কিমার সাথে API অনুরোধগুলি কীভাবে যাচাই করবেন (যেমন, AJV জাভাস্ক্রিপ্টের জন্য, jsonschema পাইথনের জন্য)
5. কিভাবে CI/CD পাইপলাইনে JSON স্কিমা বৈধতা একত্রিত করবেন
6. এর মাধ্যমে একাধিক API অনুরোধ জুড়ে স্কিমা পুনরায় ব্যবহার করার চেষ্টা করুন $ref

সাধারণ ক্ষতি এবং সেগুলি কীভাবে এড়ানো যায়

এখন আপনি আপনার ধরন, বৈশিষ্ট্য এবং বৈধতা সব লাইন আপ পেয়েছেন, এবং আপনার API বেশ কঠিন দেখাচ্ছে. কিন্তু এই মুহুর্তে, দূরে নিয়ে যাওয়া এবং ভুল করা খুবই সাধারণ ব্যাপার। এটি আপনাকে বা আপনার ব্যবহারকারীদের একটি খুব হতাশাজনক পরিস্থিতিতে নিয়ে যেতে পারে। আসুন কিছু কেস কভার করি এবং সেগুলি এড়াতে সম্ভাব্য সমাধানগুলি দেখি৷

1. অত্যধিক কঠোর বনাম অতিমাত্রায় নমনীয় স্কিমা

JSON স্কিমা নিয়মগুলির সাথে কিছুটা দূরে থাকা সহজ। এক মিনিটে আপনি কয়েকটি বুদ্ধিমান যাচাইকরণ সেট আপ করছেন এবং পরের মিনিটে আপনি প্রতিটি অনুরোধ ব্লক করছেন যা আপনার সাথে খাপ খায় না সঠিক নিখুঁত তথ্য ধারণা। অন্য দিকে, আপনি যদি খুব নম্র হন, তাহলে আপনি একটি বিশৃঙ্খল API এর সাথে শেষ করবেন যেখানে মোটামুটি কিছু যায়। সঠিক ভারসাম্য খুঁজে পাওয়া গুরুত্বপূর্ণ।

তাই আপনি জিজ্ঞাসা করতে পারেন — কিভাবে কঠোর খুব কঠোর?

কল্পনা করুন আপনার কাছে একটি ব্যবহারকারী প্রোফাইলের জন্য একটি স্কিমা আছে এবং আপনি এটি সেট আপ করেছেন যাতে একগুচ্ছ ফিল্ডের প্রয়োজন হয় firstName, lastName, phoneNumber, addressএবং bio. কিন্তু তারপর কেউ একটি নতুন প্রোফাইল তৈরি করার চেষ্টা করে এবং – ওহ – তারা একটি বায়ো মিস করছে। যে সত্যিই একটি চুক্তি ভঙ্গকারী হওয়া উচিত?

• খুব কঠোর হওয়ার সমস্যা: আপনি যদি প্রয়োজনীয় ক্ষেত্রগুলির সাথে খুব কঠোর হন, তাহলে আপনি ব্যবহারকারীদের তাদের না থাকতে পারে বা প্রয়োজনের বিষয়ে অবরুদ্ধ করবেন। তারা হতাশ হবে, এবং আপনার API বন্ধুত্বহীন দেখাবে।
• খুব নম্র হওয়ার সমস্যা: আপনি যদি খুব সহজে যান, যেমন প্রতিটি ক্ষেত্রকে ঐচ্ছিক করা এবং কোনো সীমাবদ্ধতা যোগ না করা, তাহলে আপনার শেষ হবে জাঙ্ক ডেটা—খালি ক্ষেত্র, ভুল ফরম্যাট এবং সব ধরনের অদ্ভুত এন্ট্রি। আপনার ডাটাবেস একটি জগাখিচুড়ি হয়ে যায়, এবং যখন আপনি সেই ডেটা ব্যবহার করার চেষ্টা করেন তখন যাচাইকরণের সমস্যাগুলি পরে দেখা যায়।

মিষ্টি স্পট খোঁজা

শুধুমাত্র প্রয়োজনীয় ক্ষেত্রগুলি তৈরি করে শুরু করুন (যেমন userId এবং email একটি ব্যবহারকারী স্কিমার জন্য)। তারপর, বুদ্ধিমান সীমাবদ্ধতা যোগ করুন, কিন্তু এটি অতিরিক্ত করবেন না। এটি এইভাবে চিন্তা করুন: যদি একটি অনুপস্থিত ক্ষেত্র আসলে আপনার API ভাঙ্গে না, সম্ভবত এটির প্রয়োজন হবে না।

উদাহরণ:

{
   "type": "object",
   "properties": {
      "userId": { "type": "string" },
      "email": { "type": "string", "format": "email" },
      "phoneNumber": { "type": "string", "minLength": 10 },
      "bio": { "type": "string", "maxLength": 250 }
   },
   "required": ("userId", "email")
}

এখানে, userId এবং email প্রয়োজন হয় phoneNumber এবং bio খুব ভালো জিনিস আছে, কিন্তু তারা অনুপস্থিত থাকলে অনুরোধটি ব্লক করবে না।

2. স্কিমা আপডেটের সাথে পশ্চাদগামী সামঞ্জস্য নিশ্চিত করা

আহ, পশ্চাদপদ সামঞ্জস্য!!! যখনই আপনি ডেটা গঠনের একটি ভাল উপায় খুঁজে পান তখনই এটি আপনার স্কিমা আপডেট করতে প্রলুব্ধ করে, তবে এটি খুব ঘন ঘন পরিবর্তন করা বড় সমস্যা সৃষ্টি করতে পারে। যদি বিদ্যমান ক্লায়েন্টরা একটি নির্দিষ্ট কাঠামোর উপর নির্ভর করে, তবে সেই কাঠামো পরিবর্তন করা তাদের ভেঙ্গে ফেলবে।

পশ্চাদপদ সামঞ্জস্যতা পিটফল

ধরুন আপনি নাম পরিবর্তন করে আপনার ব্যবহারকারীর স্কিমা আপডেট করার সিদ্ধান্ত নিয়েছেন phoneNumber থেকে mobileNumber. যথেষ্ট ক্ষতিকারক মনে হচ্ছে, তাই না? ভুল. এখন, যে কেউ পুরানো ব্যবহার করে phoneNumber ক্ষেত্র ত্রুটি পেতে যাচ্ছে, এবং হঠাৎ আপনার সমর্থন ইনবক্স প্লাবিত হয় “আমার API কি হয়েছে?!”

ব্রেকিং পরিবর্তন এড়াতে কিভাবে

• নতুন ক্ষেত্র যোগ করুন, প্রতিস্থাপন করবেন না: আপনি একটি নতুন ক্ষেত্র যোগ করতে চান, এটি জন্য যান! তবে বিদ্যমান ক্ষেত্রগুলির নাম পরিবর্তন বা সরানোর চেষ্টা করবেন না। যদি আপনাকে একটি ক্ষেত্রের নাম পরিবর্তন করতেই হয়, নতুন ক্ষেত্রটিকে ঐচ্ছিক হিসাবে যোগ করার এবং আপনার ডকুমেন্টেশনে পুরানোটিকে “অপ্রচলিত” হিসাবে চিহ্নিত করার কথা বিবেচনা করুন৷ এইভাবে, আপনি কোনো বিদ্যমান ক্লায়েন্ট ভাঙ্গবেন না।
• সংস্করণ আপনার API: আপনি যদি একটি বড় পরিবর্তন করছেন যা বিদ্যমান সেটআপগুলিকে ভেঙে ফেলবে, আপনার API এর একটি নতুন সংস্করণ তৈরি করার কথা বিবেচনা করুন (v2), যাতে লোকেরা প্রস্তুত হলে আপগ্রেড করা বেছে নিতে পারে৷ সম্ভব হলে ব্যবহার করুন semantic versioning.
• পরিবর্তনের সাথে যোগাযোগ করুন: যদি আপনাকে কোনো পরিবর্তন করতেই হয়, আপনার ব্যবহারকারীদের সাথে অগ্রসর হোন। এটি আপনার চেঞ্জলগে যোগ করুন, একটি ইমেল পাঠান, বা আপনার ডক্সে একটি নোটিশ রাখুন।

চমক জন্মদিনের জন্য দুর্দান্ত, API আপডেটের জন্য এত বেশি নয়।

ব্রেকিং পরিবর্তনগুলি হ্যান্ডেল করার বিভিন্ন উপায় আছে যদি আপনাকে একেবারে একটি করতে হয়। হয় আপনি আপনার নিজের গবেষণা করতে পারেন বা আমাকে জানাতে পারেন যে আমি এটির উপর অন্য নিবন্ধ লিখব কিনা। (কে জানে, হয়তো আমি আগামী 2-3 বছরের মধ্যে এটি করব?)

চূড়ান্ত চিন্তা – কেন আপনি JSON স্কিমা চেষ্টা করা উচিত

সুতরাং, আপনি এটি শেষ পর্যন্ত করেছেন — আপনি কি, একটি বিরল জাত, একটি সুপারফ্যান, নাকি শুধু আমার আত্মার বন্ধু? কারণ আপনি আসলে পুরোটা পড়েন! আপনাকে ধন্যবাদ (এবং হয়তো আমার কাছে এমন একটি মনোমুগ্ধকর লেখার জন্য)।

কিন্তু আপনি যদি এখন পর্যন্ত আমার সাথে থাকেন, এখন এটি চেষ্টা করার জন্য একটি দুর্দান্ত সময়। একটি API অনুরোধ বা প্রতিক্রিয়ার জন্য একটি ছোট স্কিমা হতে পারে—এবং এটি কীভাবে জিনিসগুলিকে সংগঠিত রাখতে সাহায্য করে তা দেখুন৷ একবার আপনি সুবিধাগুলি দেখতে পেলে, এটি প্রসারিত করা সহজ, আরও শেষ পয়েন্টের জন্য স্কিমা যোগ করা এবং একটি সুগঠিত API তৈরি করা।

JSON স্কিমা প্রথমে অতিরিক্ত কাজের মত মনে হতে পারে, কিন্তু পেঅফ বিশাল। আপনি একটি ক্লিনার, আরও অনুমানযোগ্য API এর সাথে শেষ করবেন যা বজায় রাখা সহজ, এবং যে কেউ আপনার API ব্যবহার করে (আপনি সহ) পরিষ্কার কাঠামো এবং বৈধতার প্রশংসা করবে৷ এটি সেই সরঞ্জামগুলির মধ্যে একটি যা আপনাকে কম প্রচেষ্টায় আরও নিয়ন্ত্রণ দেয় – এবং এটি কে না চায়?

সুতরাং, আমাকে জানাতে দিন যে এটি পড়ার মূল্য ছিল, যদি আপনি একটি বা দুটি জিনিস শিখে থাকেন, বা যদি আপনি একটি JSON স্কিমাতে ডুব দিচ্ছেন এবং বাস্তবায়ন করছেন। আমি আপনার চিন্তা শুনতে চাই — এবং আমি আপনাকে স্কিমা দিকে রূপান্তরিত করেছি কিনা তা দেখুন।

পরবর্তী পদক্ষেপ

ঠিক আছে, JSON স্কিমা আপনার API গুলি সংগঠিত করার একমাত্র উপায় নয়। আপনি ব্যবহার করতে পারেন বিভিন্ন অন্যান্য পদ্ধতি/সরঞ্জাম আছে. আপাতত, আপনার নিজের গবেষণা করুন। অথবা শুধু আমার পরবর্তী ব্লগের জন্য অপেক্ষা করুন (আমি আশা করি এটি শীঘ্রই বেরিয়ে আসবে)!

এখানে আপনার কিছু গবেষণার বিষয় রয়েছে:

1. প্রোটোবাফ এবং জিআরপিসি: প্রোটোকল বাফার (প্রোটোবুফ), Google দ্বারা তৈরি, ডেভেলপারদের একটি ভাষা-নিরপেক্ষ বিন্যাসের সাথে কঠোর ডেটা চুক্তি সংজ্ঞায়িত করতে দেয় যা দক্ষ এবং কম্প্যাক্ট। gRPC-এর সাথে যুক্ত, এই পদ্ধতিটি পরিষেবা জুড়ে দ্রুত যোগাযোগ এবং ডেটা বৈধতা সক্ষম করে।
2. io-ts বা zod সহ টাইপস্ক্রিপ্ট: এই লাইব্রেরিগুলি (যেমন io-ts এবং zod) আপনাকে টাইপস্ক্রিপ্ট প্রকারগুলি ব্যবহার করে রানটাইমে বৈধতা নিয়মগুলি সংজ্ঞায়িত করতে দেয়, স্ট্যাক জুড়ে ডেটা সামঞ্জস্য নিশ্চিত করে৷ এটি নকল এড়ায়, কারণ একই সংজ্ঞা টাইপ চেকিং এবং বৈধতা উভয়ের জন্য ব্যবহার করা যেতে পারে।
3. হ্যাঁ: এটি বৈধকরণ স্কিমা তৈরির জন্য একটি পরিষ্কার API প্রদান করে, বিশেষত জটিল, নেস্টেড অবজেক্টের জন্য দরকারী। এটি প্রতিক্রিয়ার মতো ফ্রন্ট-এন্ড ফ্রেমওয়ার্কগুলির সাথে অত্যন্ত সামঞ্জস্যপূর্ণ এবং ফর্মিকের মতো ফর্ম লাইব্রেরির সাথে ভালভাবে সংহত করে৷
4. গ্রাফকিউএল: অনমনীয় স্কিমাগুলির পরিবর্তে, গ্রাফকিউএল স্কিমাগুলি ন্যূনতম সংস্করণের সাথে বিকশিত হতে পারে, যা ব্যাকএন্ড এবং ফ্রন্টএন্ড উভয় বিকাশকারীদের জন্য আরও তরল অভিজ্ঞতা প্রদান করে।