পাঠ্যক্রম খুলুন

প্রাথমিক পর্যায়

API Versioning: পুরোনো client সচল রেখে পরিবর্তন

API Versioning and Compatibility

এই পাঠের কুইজ ↓৫ মিনিট পড়াPHP 8.3+ · Laravel 12

আগে পড়ে নিনREST API: resource, validation ও error response ↗

এই পাঠের সূচিপত্র

এই পাঠে যা শিখবেন

Breaking ও compatible change
URL, header ও representation version
Expand-contract migration ও client transition

সমস্যা দিয়ে শুরু

Mobile app পুরোনো release-এ amount field integer আশা করে। Server deploy-এ field object হয়ে গেলে app crash করে, যদিও endpoint path একই। API versioning মানে শুধু /v2 লেখা নয়; পুরোনো client-এর contract কীভাবে বাঁচবে এবং migration কখন শেষ হবে তা পরিকল্পনা করা।

সহজ করে বুঝি

Breaking change existing valid client behavior ভাঙে: field remove/rename, type change, নতুন required input বা error semantics বদলানো। Optional output field যোগ সাধারণত compatible হতে পারে, তবে strict client অজানা field reject করলে contract test দরকার। URL version explicit ও cache-friendly, header/media-type version cleaner URL দেয় কিন্তু routing/caching visibility জটিল। Version number database schema version-এর সঙ্গে এক হওয়া বাধ্যতামূলক নয়।

পরিচিত একটি উপমা

বিদ্যুতের socket বদলালে পুরোনো plug চলবে কি না ভাবতে হয়। নতুন socket পাশাপাশি রেখে adapter দেওয়া transition সহজ করে। একই নামের socket-এ হঠাৎ voltage বদলালে label একই থেকেও পুরোনো যন্ত্র নষ্ট হতে পারে—API semantics-এর পরিবর্তনও এমন।

নকশাটি দেখুন

Diagram লোড হচ্ছে…

দুটি external representation shared business action ব্যবহার করে।

Diagram-এর text flow দেখুন

flowchart TD
 O[Old clients] --> V1[API v1 representation]
 N[New clients] --> V2[API v2 representation]
 V1 --> A[Shared domain action]
 V2 --> A
 A --> D[(Compatible evolving schema)]
 V1 --> T[Measured deprecation plan]

দুটি external representation shared business action ব্যবহার করে। এতে pricing invariant দুই controller-এ duplicate হওয়ার ঝুঁকি কমে। Schema transition period-এ দুটো representation serve করতে পারে। Deprecation plan usage telemetry, client owner communication এবং deadline রাখে; নতুন version release হলেই পুরোনো version পরদিন মুছে ফেলা নিরাপদ নয়।

PHP ও Laravel-এ প্রয়োগ

routes/api.php fragment এবং simple explicit representation। Product model-এ price_minor ও currency fields আছে ধরে নেওয়া হয়েছে; production-এ resources ব্যবহার করতে পারেন। Default /api prefix-সহ route হবে /api/v1/products/{product} ও /api/v2/products/{product}। Public product data কেবল দেখানো হচ্ছে।

use App\Models\Product;
use Illuminate\Support\Facades\Route;

Route::get('/v1/products/{product}', fn (Product $product) => [
    'id' => $product->id,
    'price_minor' => $product->price_minor,
]);
Route::get('/v2/products/{product}', fn (Product $product) => [
    'id' => $product->id,
    'price' => [
        'amount_minor' => $product->price_minor,
        'currency' => $product->currency,
    ],
]);

সুবিধা, সীমাবদ্ধতা ও trade-off

Parallel versions client transition সহজ করে, কিন্তু test ও maintenance surface বাড়ায়। Backward-compatible evolution দীর্ঘস্থায়ী version proliferation কমায়। Header version-এ CDN Vary/key policy ভুল হলে এক client অন্য version পেতে পারে। URL version visible, তবে সব field change-এ major bump করলে ecosystem জটিল হয়। Version policy-তে supported lifetime ও emergency security exception লিখুন।

সাধারণ ভুল

পুরোনো client ব্যবহার করছে কি না না মেপে endpoint সরানো।
Additive enum value সব client safe ভাবে handle করবে ধরে নেওয়া।
Database migration ও API removal একই deploy-এ বেঁধে ফেলা।

আরও একটু গভীরে

Expand-contract-এ আগে নতুন schema/field যোগ, compatible code deploy, data backfill, consumer migrate, শেষে পুরোনো field remove। Rolling deploy-এ পুরোনো ও নতুন app একসঙ্গে চলতে পারে; API ও DB উভয় contract দুই release support করতে হতে পারে। Contract test-এ old request fixtures ও response expectations চালান। Logs-এ API version dimension রাখুন, sensitive token label নয়।

মনে রাখুন

Compatibility user-visible behavior দিয়ে বিচার করুন। Version একটি transition tool, maintenance-free solution নয়। Shared domain logic ও measured deprecation migration নিরাপদ করে।

নিজে চেষ্টা করুন

price_minor থেকে money object-এ পরিবর্তনের migration plan লিখুন। Old mobile app ছয় মাস update না হলে support policy কী হবে বলুন। Error code, enum এবং pagination token change-এর কোনটি breaking হতে পারে উদাহরণ দিন।

নিজের বোঝা যাচাই করুন

1. নতুন field সবসময় safe?

সাধারণত additive, কিন্তু strict deserializer বা generated client reject করতে পারে। Published contract ও representative client tests দেখুন।

2. URL version বাধ্যতামূলক?

না। Header বা media type-ও সম্ভব। Routing, documentation ও cache behavior দেখে choice করুন।

3. DB schema আর API version একই?

না। External contract stable রেখেও internal schema বদলানো যায়। Transformation layer boundary তৈরি করে।

4. Old version কবে বন্ধ?

Usage evidence, announced policy ও client migration support অনুযায়ী। Unknown active clients থাকলে risk স্পষ্ট করতে হবে।

5. Enum addition breaking কেন?

Client exhaustive switch-এ unknown case handle না করলে crash হতে পারে। Forward-compatible client behavior contract-এ রাখা ভালো।

এই পাঠের কুইজ

এই পাঠ থেকে ২টি প্রশ্ন। উত্তর দিয়ে ব্যাখ্যা দেখুন; অধ্যায়ের কুইজ আলাদাভাবে দিতে হবে।

এই পাঠের ২টি প্রশ্নের উত্তর দিন। পাস করতে দুটিই সঠিক হতে হবে।

জমা দেওয়ার পর সঠিক উত্তর ও ব্যাখ্যা দেখবেন। ফলাফল এই ব্রাউজারে সংরক্ষিত থাকবে। অনুশীলনের ফল অধ্যায় সম্পন্নের হিসাবে যোগ হয় না।

সব বিষয় মিলিয়ে অনুশীলন করুন →

অগ্রগতি এই ব্রাউজারে সংরক্ষিত থাকে। শুধু পাঠ খুললে সম্পন্ন হয় না।