API Versioning: ඔබේ REST API නඩත්තු කරමු | SC Guide

කොහොමද යාලුවනේ? ඔන්න අද අපි කතා කරන්න යන්නේ ඔයාලා හැමෝටම ගොඩක් වැදගත් වෙන, ඒත් සමහර විට එතරම් අවධානයක් නොදෙන මාතෘකාවක් ගැන – ඒ තමයි API Versioning.

හිතන්නකෝ, ඔයාලා App එකක් හරි, Web Site එකක් හරි හදනවා. ඒකට Backend එකෙන් API එකක් හරහා Data එනවා. මුලදී හැමදේම ලස්සනට වැඩ කළා. හැබැයි කාලයත් එක්ක අලුත් Features දාන්න වෙනවා, පරණ Features වෙනස් කරන්න වෙනවා. සමහර වෙලාවට Data Structure එකත් වෙනස් කරන්න වෙනවා. මෙහෙම කරද්දි මොකද වෙන්නේ? ඔයාලගේ App එකේ පරණ Version පාවිච්චි කරන Clients ලා හදිස්සියේම කැඩිලා යනවා (Breaking Changes!). මේක Developer කෙනෙක් විදියට අපිට ලොකු ඔළුවිසූවක්, Clients ලටත් එපා වෙන වැඩක්.

මෙන්න මේ ප්‍රශ්නයට තමයි API Versioning කියන එක අපිට පිහිටට එන්නේ. මේක හරියට පොතක Revision වගේ, නැත්නම් Software එකක Versions වගේ. අපි අලුත් වෙනස්කම් කරනකොට, ඒක අලුත් Version එකක් විදියට Release කරනවා. එතකොට පරණ Client ලට කිසිම කරදරයක් නැතුව පරණ Version එක දිගටම පාවිච්චි කරන්න පුළුවන්. අලුත් Client ලට අලුත් Version එකට Upgrade වෙන්න පුළුවන්. මේකෙන් අපේ API එක Long-Term Maintain කරන්න පුළුවන්.

ඉතින්, අද අපි මේ Guide එකෙන් බලමු API Versioning කියන්නේ මොකක්ද, මොනවද තියෙන ක්‍රමවේද, හොඳම Practices මොනවද, සහ කොහොමද අපි අපේ REST API එකක් Version කරගන්නේ කියලා. අන්තිමට, අපි පොඩි Code Example එකකුත් බලමු. එහෙනම්, අපි පටන් ගමු!

API Versioning කියන්නේ මොකක්ද? (What is API Versioning?)

සරලවම කිව්වොත්, API Versioning කියන්නේ අපේ API එකට කාලයත් එක්ක වෙනස්කම් කරන්න, ඒත් ඒ වෙනස්කම් නිසා දැනට පාවිච්චි කරන Clients ලට හානියක් නොවෙන්න manage කරන ක්‍රියාවලියට. හිතන්නකෝ ඔයාලගේ App එකට Users ලගේ Details ගන්න API Endpoint එකක් තියෙනවා කියලා: /api/users.

මුලදී මේකෙන් id, name, email වගේ දේවල් විතරයි දුන්නේ. දැන් ඔයාලට ඕනේ phone_number, address, profile_picture_url වගේ අලුත් Dataත් එකතු කරන්න. ඒ වගේම, name කියන එක full_name විදියටත්, id කියන එක user_id විදියටත් වෙනස් කරන්න ඕනේ කියලා හිතන්න. මේ වගේ වෙනස්කම් කෙලින්ම /api/users Endpoint එකට කළොත් මොකද වෙන්නේ? පරණ Clients ලා මේ අලුත් Data Structure එක ගැන දන්නේ නැහැ, ඒ නිසා App එකේ Error එන්න පටන් ගන්නවා.

මේ වෙලාවේ තමයි අපි Versioning පාවිච්චි කරන්නේ. අපි මේ අලුත් වෙනස්කම් එක්ක අලුත් API Version එකක් Release කරනවා. උදාහරණයක් විදියට, පරණ එක v1 විදියට තියලා, අලුත් එක v2 විදියට හදනවා. එතකොට පරණ Clients ලට v1 එක දිගටම පාවිච්චි කරන්න පුළුවන්, අලුත් Clients ලට v2 එකට යන්න පුළුවන්. මේකෙන් Client-Server Compatibility එක maintain කරගන්න පුළුවන් වෙනවා.

මේකේ ප්‍රධානම වාසිය තමයි, අපිට API එකේ අලුත් Features සහ Improvements Release කරන්න නිදහස ලැබෙන එක. Clients ලට ක්ෂණිකව Upgrade වෙන්න කියලා බල කරන්න ඕනේ නැහැ. ඒ වගේම, අපිට යම් කාල සීමාවක් දීලා, පරණ Versions Deprecate කරන්නත් පුළුවන්. මේක නිසා, දීර්ඝ කාලීනව අපේ API එක Manage කරන එක ගොඩක් පහසු වෙනවා.

API Versioning ක්‍රමවේද (API Versioning Strategies)

API Versioning කරන්න විවිධ ක්‍රම කිහිපයක්ම තියෙනවා. ඒ හැම එකකටම තියෙනවා ඒවගේම වාසි සහ අවාසි. අපි බලමු ප්‍රධාන ක්‍රම මොනවද කියලා.

1. URI Path Versioning (URL එකේ Version එක දාන එක)

මේක තමයි ගොඩක්ම ජනප්‍රිය සහ තේරුම් ගන්න පහසුම ක්‍රමය. අපි API Endpoint එකේ Path එකටම Version එක එකතු කරනවා.

උදාහරණ:

• https://api.example.com/v1/users
• https://api.example.com/v2/users

වාසි:

• ගොඩක් පැහැදිලියි (Clear and Obvious): Client කෙනෙක්ට URL එක දැක්ක ගමන්ම මේක මොන Version එකද කියලා තේරෙනවා.
• Browser Friendly: Browser එකේ කෙලින්ම test කරන්න පුළුවන්.
• Easy to Cache: Different URLs for different versions makes caching straightforward.

අවාසි:

• URL Bloat: URL එක දිග වැඩි වෙනවා.
• Routing Complexity: Server පැත්තේ Routing logic එක ටිකක් සංකීර්ණ වෙන්න පුළුවන්, විශේෂයෙන් versions ගොඩක් තියෙනවා නම්.
• Not Purely RESTful: REST Architecture එකේදී URI එකක් Resource එකක් identify කරන්න විතරයි පාවිච්චි කරන්නේ, Version එකක් specify කරන්න නෙවෙයි කියලා සමහරු කියනවා.

2. Query Parameter Versioning (Query String එකේ Version එක දාන එක)

මේ ක්‍රමයේදී අපි Query Parameter එකක් විදියට Version එක Request එකට එකතු කරනවා.

උදාහරණ:

• https://api.example.com/users?version=1
• https://api.example.com/users?v=2

වාසි:

• Clean URI: URL Path එක cleaner, Version එකක් නැතුව තියෙනවා.
• Flexible: Client පැත්තෙන් Version එක manipulate කරන්න පහසුයි.

අවාසි:

• Not RESTful: REST Architecture එකේදී Query Parameters use කරන්නේ Resource එකක් Filter කරන්න මිසක් ඒකේ Version එක specify කරන්න නෙවෙයි.
• Caching Issues: සමහර විට Caching mechanisms වලදී එකම URL එකට different responses එන නිසා ප්‍රශ්න ඇතිවෙන්න පුළුවන්.
• Less Discoverable: Client කෙනෙක්ට URL එක දැකලා කෙලින්ම Version එක මොකක්ද කියලා තේරෙන්නේ නැහැ.

3. Header Versioning (HTTP Header එකේ Version එක දාන එක)

මේ ක්‍රමයේදී අපි Custom HTTP Header එකක් පාවිච්චි කරලා Version එක specify කරනවා.

උදාහරණ:

• GET /users HTTP/1.1
Host: api.example.com
X-API-Version: 1
• GET /users HTTP/1.1
Host: api.example.com
X-API-Version: 2

වාසි:

• Clean URI: URL Path එක ගොඩක් clean.
• RESTful: Resource එක identify කරන URI එක වෙනස් වෙන්නේ නැහැ.

අවාසි:

• Less Discoverable: Client කෙනෙක්ට curl command එකක් වගේ දෙයකින් පවා Version එක specify කරන්න වෙනවා. Browser එකෙන් කෙලින්ම test කරන්න බැහැ.
• Requires Client Configuration: Client පැත්තෙන් Headers configure කරන්න ඕනේ.

4. Media Type Versioning (Content Negotiation / Accept Header)

මේක තමයි REST Architecture එකට ගොඩක්ම ගැලපෙන ක්‍රමය කියලා කියන්නේ. මෙතනදී අපි Accept Header එක පාවිච්චි කරලා Client එකට ඕනේ මොන Media Type එකද කියලා කියනවා. Media Type එකට Version එක ඇතුලත් කරනවා.

උදාහරණ:

• GET /users HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v1+json
• GET /users HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v2+json

වාසි:

• Highly RESTful: HTTP Spec එකට සම්පූර්ණයෙන්ම ගැලපෙනවා.
• Clean URI: URI එකට Version එකක් එකතු වෙන්නේ නැහැ.

අවාසි:

• Complex to Implement: Server පැත්තෙන් Implementation එක ටිකක් සංකීර්ණ වෙන්න පුළුවන්.
• Less Intuitive: Client කෙනෙක්ට තේරුම් ගන්න ටිකක් අමාරු වෙන්න පුළුවන් මුලින්.
• Documentation is Key: මේ ක්‍රමය පාවිච්චි කරනවා නම් documentation ඉතාම වැදගත්.

අපේ Recommendation:

ගොඩක් වෙලාවට කුඩා සහ මධ්‍යම ප්‍රමාණයේ Project වලට URI Path Versioning (/v1/users) තමයි හොඳම. ඒක තේරුම් ගන්න පහසුයි, Implement කරන්න පහසුයි, සහ ගොඩක් Tools වලට හොඳට support කරනවා. Large-scale Enterprise Systems වලට Header Versioning හෝ Media Type Versioning ගැන හිතන්න පුළුවන්, මොකද ඒවයින් URI එක clean තියාගන්න පුළුවන් නිසා.

හොඳම Practices (Best Practices)

API Versioning කරද්දී මතක තියාගන්න ඕනේ වැදගත් කරුණු කිහිපයක් තියෙනවා:

1. Consistency තමයි රජු (Consistency is King)

ඔබ තෝරාගන්නා Versioning ක්‍රමවේදය කුමක් වුවත්, එය ඔබගේ සම්පූර්ණ API එක පුරාම එක හා සමානව භාවිතා කරන්න. සමහර Endpoints වල URI Path එකත්, තව සමහර Endpoints වල Header එකත් පාවිච්චි කරන්නේ නැතුව, එකම ක්‍රමයක් තෝරාගෙන ඒකම පාවිච්චි කරන්න. මේක Clients ලට ඔබේ API එක තේරුම් ගන්න සහ භාවිතා කරන්න ගොඩක් පහසු වෙනවා.

2. Deprecation Policy එකක් තියාගන්න (Have a Deprecation Policy)

පරණ API Versions සදහටම තියාගන්න බැහැ. ඒක Maintenance Cost එක වැඩි කරනවා. ඒ නිසා, පරණ Version එකක් කවදාද Deprecate කරන්නේ (තවදුරටත් support නොකරන්නේ) සහ කවදාද සම්පූර්ණයෙන්ම ඉවත් කරන්නේ (Sunset) කියන එකට පැහැදිලි Policy එකක් තියාගන්න. උදාහරණයක් විදියට: "අලුත් Version එකක් Release කළාට පස්සේ, පරණ Version එක තව මාස 6ක් Support කරනවා, ඊට පස්සේ සම්පූර්ණයෙන්ම ඉවත් කරනවා." මේ ගැන Clients ලට කලින්ම දන්වන්න. මේවා Documentation වල පැහැදිලිව සඳහන් කරන්න.

3. Documentation කියන්නේ ජීවිතේ (Documentation is Life)

ඔබේ API එකේ හැම Version එකක්ම, ඒවායේ වෙනස්කම්, Request/Response Structures, සහ Deprecation Schedule එක පැහැදිලිව Document කරන්න. Swagger/OpenAPI වගේ Tools මේකට ගොඩක් ප්‍රයෝජනවත්. හොඳ Documentation එකක් නැත්නම් Clients ලට ඔබේ API එක පාවිච්චි කරන්න බැහැ.

4. Backward Compatibility ගැන හිතන්න (Think About Backward Compatibility)

සෑම Version වෙනස්කමක්ම Breaking Change එකක් වෙන්න ඕනේ නැහැ. පුළුවන් තරම් Backward Compatible වෙනස්කම් කරන්න උත්සාහ කරන්න. උදාහරණයක් විදියට, Response එකකට අලුත් Field එකක් එකතු කරන එක Backward Compatible වෙනස්කමක්. ඒත් තියෙන Field එකක් Rename කරන එක හෝ අයින් කරන එක Breaking Change එකක්. Breaking Changes හැකිතාක් අඩුවෙන් කරන්න, සහ ඒ වගේ වෙලාවට විතරක් අලුත් Major Version එකක් Release කරන්න.

5. හොඳින් Test කරන්න (Test Thoroughly)

ඔබේ API එකේ හැම Version එකක්ම, සියලුම Endpoints සහ Use Cases හරහා හොඳින් Test කරන්න. Automated Tests මේකට ගොඩක් වැදගත්. Versions අතර වෙනස්කම් හරියට වැඩ කරනවද කියලා තහවුරු කරගන්න.

6. Monitor කරන්න (Monitor Usage)

ඔබේ API එකේ කුමන Version එකද Clients ලා වැඩිපුරම පාවිච්චි කරන්නේ කියලා Monitoring Tools වලින් බලාගන්න. මේකෙන් ඔබට පරණ Versions කවදාද Deprecate කරන්න පුළුවන් කියලා තීරණය කරන්න උදව් වෙනවා.

REST API එකක් Version කරන්නේ කොහොමද? (How to Version a REST API?)

හොඳයි, දැන් අපි ගොඩක් දේවල් කතා කළානේ. අපි පොඩි Example එකක් බලමු Node.js සහ Express.js පාවිච්චි කරලා, URI Path Versioning ක්‍රමයට API එකක් Version කරන්නේ කොහොමද කියලා.

මුලින්ම අපි Express Project එකක් හදාගමු:

mkdir api-versioning-example
cd api-versioning-example
npm init -y
npm install express

ඊට පස්සේ, server.js කියලා File එකක් හදලා මේ Code එක දාමු.

// server.js
const express = require('express');
const app = express();
const PORT = 3000;

app.use(express.json()); // To parse JSON request bodies

// --- API Version 1 (v1) ---
// Features: Get users with basic info (id, name, email)
app.get('/api/v1/users', (req, res) => {
    console.log('Serving /api/v1/users');
    const users = [
        { id: 1, name: 'Kasun Perera', email: '[email protected]' },
        { id: 2, name: 'Amali Silva', email: '[email protected]' }
    ];
    res.json(users);
});

app.get('/api/v1/products', (req, res) => {
    console.log('Serving /api/v1/products');
    const products = [
        { productId: 'P001', productName: 'Laptop' },
        { productId: 'P002', productName: 'Mouse' }
    ];
    res.json(products);
});

// --- API Version 2 (v2) ---
// Features:
// - Users endpoint: Changed field names (userId, fullName), added phone
// - Products endpoint: Added description, category
app.get('/api/v2/users', (req, res) => {
    console.log('Serving /api/v2/users');
    const users = [
        { userId: 1, fullName: 'Kasun Perera', email: '[email protected]', phone: '0711234567' },
        { userId: 2, fullName: 'Amali Silva', email: '[email protected]', phone: '0779876543' }
    ];
    res.json(users);
});

app.get('/api/v2/products', (req, res) => {
    console.log('Serving /api/v2/products');
    const products = [
        { productId: 'P001', productName: 'Laptop', description: 'High-performance laptop', category: 'Electronics' },
        { productId: 'P002', productName: 'Mouse', description: 'Wireless optical mouse', category: 'Accessories' }
    ];
    res.json(products);
});

// Default route for root path
app.get('/', (req, res) => {
    res.send('Welcome to the API Versioning Example!');
});

// Start the server
app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}`);
});

මේ Code එකේ අපි /api/v1 සහ /api/v2 කියලා Paths දෙකක් හදලා තියෙනවා. මේක URI Path Versioning ක්‍රමයට උදාහරණයක්.

දැන් මේ Server එක Run කරමු:

node server.js

ඊට පස්සේ ඔයාට Postman, Insomnia වගේ API Client එකක් පාවිච්චි කරලා, නැත්නම් Browser එකෙන්ම මේ Endpoints Call කරලා බලන්න පුළුවන්:

• Version 1 Users: http://localhost:3000/api/v1/users
• Version 2 Users: http://localhost:3000/api/v2/users
• Version 1 Products: http://localhost:3000/api/v1/products
• Version 2 Products: http://localhost:3000/api/v2/products

ඔබට පෙනේවි /api/v1/users වලින් පරණ Data Structure එකත්, /api/v2/users වලින් අලුත් Data Structure එකත් එනවා. මේකෙන් අපි Client Compatibility එක Maintain කරගන්නවා. පරණ Clients ලා v1 එකට call කරනකොට ඒගොල්ලන්ට දැනටමත් වැඩ කරන විදියට Data එනවා. අලුත් Clients ලට v2 එක පාවිච්චි කරන්න පුළුවන් අලුත් Features එක්ක.

මේක තවදුරටත් සංකීර්ණ වෙන්න පුළුවන්. උදාහරණයක් විදියට, v1 එකේ තියෙන Logic එක v2 එකටත් පාවිච්චි කරන්න පුළුවන් නම්, ඔබට Common functions හදලා ඒවාට Logic එක දාන්න පුළුවන්. v2 එකේදී විතරක් වෙනස් වන Logic එක අලුතෙන් ලියන්න පුළුවන්.

ඒ වගේම, මේක විශාල Project එකක් නම්, ඔබට routes/v1.js සහ routes/v2.js වගේ Files හදලා Routes ටික වෙනම organize කරන්නත් පුළුවන්. මේකෙන් Codebase එක Clean කරගන්න පුළුවන්.

අවසාන වශයෙන් (Conclusion)

ඉතින් යාලුවනේ, API Versioning කියන්නේ Developer කෙනෙක් විදියට අපිට අනිවාර්යයෙන්ම දැනගෙන ඉන්න ඕනේ දෙයක්. විශේෂයෙන්ම App හෝ Web Development ක්ෂේත්‍රයේ ඉන්න අයට. මේකෙන් අපිට වගේම අපේ Clients ලටත් ගොඩක් පහසුවක් වෙනවා. API එකක් කාලයත් එක්ක වර්ධනය වෙද්දි, Breaking Changes නිසා ඇතිවන හිසරදය වළක්වාගන්න මේ ක්‍රමවේද ගොඩක් වැදගත්.

අපි මේ Guide එකෙන් කතා කළා Versioning ක්‍රමවේද, Best Practices, සහ සරල Code Example එකකුත් බැලුවා. දැන් ඔබට පුළුවන් මේ දැනුම ඔබේ Project වලට යොදාගෙන, තව හොඳට API Manage කරන්න. මතක තියාගන්න, හොඳින් සැලසුම් කරපු API Versioning Strategy එකක් ඔබේ Software Project එකේ සාර්ථකත්වයට ගොඩක් වැදගත්.

ඔබ මේ ගැන අදහස් දක්වන්න කැමති නම්, නැත්නම් මේ ක්‍රමවේද ඔබේ Project වලට Implement කරද්දි ගැටලු ආවොත්, පහතින් Comment එකක් දාන්න. අපි ඒ ගැන කතා කරමු. එහෙනම්, තවත් අලුත් දෙයකින් හමුවෙමු! Happy Coding!