By Thisara Priyamal — 20 Jul 2025

REST APIs සරලව තේරුම් ගනිමු - ආරම්භකයින්ට ප්‍රායෝගික මාර්ගෝපදේශය SC Guide

Demystifying REST APIs: A Practical Guide for Beginners SC Guide

හලෝ යාළුවනේ! කොහොමද ඉතින් ඔයාලට? අද අපි කතා කරන්න යන්නේ Web Development ලෝකේ හරිම වැදගත් මාතෘකාවක් ගැන. ඒ තමයි REST APIs. මේක අහපු ගමන් සමහරුන්ට 'අප්පෝ, මේකත් අර සංකීර්ණ මොනවදෝ නේද?' කියලා හිතෙන්න පුළුවන්. ඒත් මම අද පොරොන්දු වෙනවා, මේ පෝස්ට් එක කියවලා ඉවර වෙනකොට ඔයාලට REST APIs ගැන හොඳ අවබෝධයක් ලැබෙයි කියලා. සරලවම කිව්වොත්, ඊට පස්සේ ඔයාලා කාටහරි 'REST API එකක් කියන්නේ මොකක්ද?' කියලා ඇහුවොත්, ඔයාලට ඒක හොඳට තේරුම් කරලා දෙන්න පුළුවන් වෙයි.

අද කාලේ අපි පාවිච්චි කරන Mobile Apps, Websites වගේ හැම දේම වගේ පිටිපස්සේ තියෙන්නේ මේ APIs තමයි. Facebook, Instagram, YouTube වගේ දේවල් වලට අපි දාන Photos, Videos, Posts ඔක්කොම Backend Servers එක්ක කතා කරන්නේ මේ APIs හරහා. ඒ නිසා, ඔයා Software Engineering Field එකේ ඉන්න කෙනෙක් නම්, විශේෂයෙන්ම Web Development, Mobile Development පැත්තට කැමති කෙනෙක් නම්, REST APIs ගැන දැනගන්න එක අත්‍යවශ්‍යයි. මේ Guide එකෙන් අපි REST APIs වල මූලික සංකල්ප, ඒවගේ වැදගත්කම, HTTP Methods වගේ දේවල් ප්‍රායෝගික උදාහරණත් එක්ක බලමු. එහෙනම්, අපි පටන් ගමු නේද?

REST API යනු කුමක්ද? (What is a REST API?)

මුලින්ම බලමු මේ API කියන්නේ මොකක්ද කියලා. API කියන්නේ Application Programming Interface කියන එකට. සරලවම කිව්වොත්, එක Software එකකට තව Software එකක් එක්ක කතා කරන්න උදව් කරන Medium එක තමයි API එකක් කියන්නේ. හරියට Restaurant එකක Waiter කෙනෙක් වගේ. Customer (Client) කෑම ඕඩර් කරන්නේ Waiter (API) ට. Waiter ඒක Kitchen (Server) එකට දීලා, කෑම හැදුවට පස්සේ ආපහු Customer ට ගෙනත් දෙනවා.

ඉතින්, REST API එකක් කියන්නේ මොකක්ද? REST කියන්නේ Representational State Transfer කියන එකට. මේක Architectural Style එකක්. මේ Style එකට අනුව, Web Services හදන විදිහට තමයි REST APIs කියන්නේ. මේවා Web මත වැඩ කරන්න නිර්මාණය කරලා තියෙන්නේ, ඒ නිසා ඒවාට HTTP Protocols පාවිච්චි කරනවා.

REST වල මූලික සිද්ධාන්ත (Core Principles of REST):

Client-Server Architecture: Client එකයි Server එකයි වෙන් කරලා තියෙනවා. Client එක (Web Browser, Mobile App) Server එකෙන් (Backend System) Data ඉල්ලනවා.
Stateless: Server එක Client එකේ කලින් Request ගැන මතක තියාගන්නේ නෑ. හැම Request එකක්ම අලුත් Request එකක් විදිහට සලකනවා.
Cacheable: Client පැත්තට Data Cache කරන්න පුළුවන්. ඒ කියන්නේ නිතරම ඕන වෙන Data Server එකෙන් ආයෙත් ආයෙත් ඉල්ලන්නේ නැතුව, තමන් ගාවම තියාගෙන ඉක්මනට පාවිච්චි කරන්න පුළුවන්.
Uniform Interface: මේක තමයි වැදගත්ම දේ. සම්මත විදිහකට API Calls කරනවා. මේක නිසා, Client එකට Server එක ගැන ගොඩක් දේවල් දැනගන්න ඕන වෙන්නේ නෑ.
Layered System: Client එකට තමන් ඉල්ලන Data Server එකෙන් කෙලින්ම එනවද, නැත්නම් ඒක අතරමැදි Servers හරහා එනවද කියලා දැනගන්න ඕන වෙන්නේ නෑ.

මේ නිසා, REST APIs හරිම Flexible, Scalable, Reliable වෙනවා. අද Web Development වලට මේවා මෙච්චර ජනප්‍රිය වෙන්න එක හේතුවක් මේක.

මූලික සංකල්ප: HTTP Methods, Endpoints සහ Resources (Core Concepts: HTTP Methods, Endpoints and Resources)

REST API එකක් එක්ක වැඩ කරන්න නම්, මේ මූලික සංකල්ප තේරුම් ගන්න එක අත්‍යවශ්‍යයි. මේවා තමයි REST API එකක Backbone එක.

Resources:

REST API එකක් හරහා අපි Manage කරන දේවල් තමයි Resources කියලා කියන්නේ. උදාහරණයක් විදිහට, University System එකක Students ලා, Courses, Departments වගේ දේවල් Resources වෙන්න පුළුවන්. සාමාන්‍යයෙන් මේවා URLs (Uniform Resource Locators) වලින් identify කරනවා.

Endpoints:

ඒ Resources වලට Access කරන්න පුළුවන් Specific URLs තමයි Endpoints කියන්නේ. ඒ කියන්නේ, මේවා තමයි Client එක Server එකට Request යවන Address එක.

උදාහරණයක්: https://api.example.com/students

HTTP Methods (Verbs):

Client එකට Resource එකක් සම්බන්ධයෙන් කරන්න ඕන දේ (Operation) Server එකට කියන්න මේ Methods පාවිච්චි කරනවා. මේවා තමයි අපි Web Browser එකක URL එකක් Type කරලා Enter කරනකොටත් පිටිපස්සේ සිද්ධ වෙන්නේ.

DELETE: Server එකක තියෙන Data එකක් Delete කරන්න (Delete) පාවිච්චි කරනවා.

DELETE /students/123 HTTP/1.1
Host: api.example.com

PATCH: Server එකක තියෙන Data එකක කොටසක් විතරක් Update කරන්න (Partial Update) පාවිච්චි කරනවා.

PATCH /students/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
    "age": 23
}

PUT: Server එකක තියෙන Data එකක් Update කරන්න (Update) පාවිච්චි කරනවා. සාමාන්‍යයෙන් මුළු Resource එකම Update කරන්න මේක පාවිච්චි කරනවා.

PUT /students/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
    "id": 123,
    "name": "Kamal Perera",
    "age": 23
}

POST: Server එකට අලුත් Data එකක් Create කරන්න (Create) පාවිච්චි කරනවා. (ලියන එක). අපි Facebook එකේ Post එකක් දානවා වගේ.

POST /students HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
    "name": "Kamal Perera",
    "age": 22
}

GET: Server එකකින් Data ගන්න (Retrieve) පාවිච්චි කරනවා. (කියවන එක). අපි Browser එකක URL එකකට යනකොට මේක තමයි වෙන්නේ.

GET /students HTTP/1.1
Host: api.example.com

JSON (JavaScript Object Notation):

REST APIs වල Data එහාට මෙහාට යවන්න බහුලවම පාවිච්චි කරන Format එක තමයි JSON. මේක Lightweight, Text-based format එකක්. මිනිස්සුන්ට වගේම Machines වලටත් තේරුම් ගන්න ලේසියි.

{
    "name": "Nimal Kumara",
    "age": 28,
    "isStudent": true,
    "courses": [
        "Software Engineering",
        "Data Structures"
    ]
}

ප්‍රායෝගික උදාහරණයක්: GET Request එකක් (Practical Example: A GET Request)

අපි මේවා ප්‍රායෝගිකව කොහොමද පාවිච්චි කරන්නේ කියලා බලමු. ඔයාලට පුළුවන් Browser එකක Console එකේ (F12) Network Tab එක බලන්න. එතන Requests යන්නේ එන්නේ කොහොමද කියලා බලාගන්න පුළුවන්. අපි පොඩි JavaScript code කෑල්ලකින් GET Request එකක් යවලා බලමු.

මේකට අපි Dummy API එකක් පාවිච්චි කරනවා. (e.g., JSONPlaceholder).

// JavaScript code for a GET request
fetch('https://jsonplaceholder.typicode.com/posts/1')
    .then(response => response.json()) // Response එක JSON විදිහට parse කරනවා
    .then(json => console.log(json)) // Parse කරපු JSON Data එක Console එකේ පෙන්නනවා
    .catch(error => console.error('There was a problem with the fetch operation:', error)); // Error එකක් ආවොත් අල්ලගන්නවා

මේ Code එක JavaScript Console එකේ Run කරලා බලන්න. ඔයාලට අදාල Post එකේ Data JSON Format එකෙන් ලැබෙනවා.

API Integration: තව දුරටත් ප්‍රායෝගික උදාහරණ (Further Practical Examples)

අපි පොඩි To-Do List Application එකක් හදනවා කියලා හිතමු. ඒකට API එකක් කොහොමද පාවිච්චි කරන්නේ කියලා බලමු. මේ To-Do Items තමයි අපේ Resources. ඒවට access කරන්න /todos වගේ Endpoint එකක් තියේවි.

1. අලුත් To-Do එකක් එකතු කිරීම (Adding a New To-Do - POST Request)

අපි අලුත් To-Do Item එකක් Server එකට යවන්න ඕන නම් POST Method එක පාවිච්චි කරනවා.

async function addTodo(title, completed) {
    const response = await fetch('https://jsonplaceholder.typicode.com/todos', {
        method: 'POST', // POST Method එක පාවිච්චි කරනවා
        headers: {
            'Content-Type': 'application/json' // යවන Data Type එක JSON කියලා කියනවා
        },
        body: JSON.stringify({ // JavaScript Object එක JSON String එකක් විදිහට යවනවා
            title: title,
            completed: completed,
            userId: 1
        })
    });
    const data = await response.json();
    console.log('New To-Do Added:', data);
}

// අලුත් To-Do එකක් එකතු කරමු
addTodo('Learn REST APIs', false);

මේක Run කරාම Console එකේ බලන්න. අලුත් ID එකක් එක්ක ඔයාගේ To-Do එක Server එකෙන් Save උනා කියලා Response එකක් එනවා. (JSONPlaceholder වලට මේවා ඇත්තටම save වෙන්නේ නෑ, නමුත් Response එකක් එවනවා).

2. To-Do එකක් Update කිරීම (Updating a To-Do - PUT Request)

අපි To-Do Item එකක් 'completed' කියලා Update කරන්න ඕන නම්, PUT Method එක පාවිච්චි කරනවා.

async function updateTodo(id, title, completed) {
    const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${id}`, {
        method: 'PUT',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            id: id,
            title: title,
            completed: completed,
            userId: 1
        })
    });
    const data = await response.json();
    console.log('To-Do Updated:', data);
}

// ID 1 තියෙන To-Do එක Update කරමු
updateTodo(1, 'Delectus aut autem', true);

3. To-Do එකක් Delete කිරීම (Deleting a To-Do - DELETE Request)

අවසාන වශයෙන්, To-Do එකක් Delete කරන්න DELETE Method එක පාවිච්චි කරනවා.

async function deleteTodo(id) {
    const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${id}`, {
        method: 'DELETE'
    });
    // DELETE Request එකකට සාමාන්‍යයෙන් හිස් Response එකක් නැත්නම් Status 204 (No Content) එකක් එනවා
    console.log(`To-Do with ID ${id} deleted. Status: ${response.status}`);
}

// ID 1 To-Do එක Delete කරමු
deleteTodo(1);

මේ උදාහරණ වලින් ඔයාලට හොඳටම තේරෙන්න ඇති REST API එකක් හරහා Data Manage කරන්නේ කොහොමද කියලා. Web Development වලදී මේවා ගැන හොඳ අවබෝධයක් තියෙන එක ඔයාලට ලොකු වාසියක්.

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

ඉතින් යාළුවනේ, මේ Guide එකෙන් අපි REST APIs වල මූලික සංකල්ප, ඒවගේ වැඩ කරන විදිහ සහ ප්‍රායෝගිකව ඒවාවලින් ප්‍රයෝජන ගන්න හැටි ගැන කතා කළා. APIs කියන්නේ අද Web ලෝකයේ BackBone එක කිව්වොත් නිවැරදියි. GET, POST, PUT, DELETE වගේ HTTP Methods පාවිච්චි කරලා කොහොමද Resources එක්ක interact කරන්නේ කියලා අපි දැක්කා. ඒ වගේම JSON වල වැදගත්කමත් අපි කතා කළා.

දැන් ඔයාලාට REST APIs ගැන හොඳ ආරම්භක දැනුමක් තියෙනවා. මේක Software Development වලදී ඔයාලට ගොඩක් වැදගත් වෙයි. අදම ගිහින් Postman, Insomnia වගේ Tools ටිකක් Install කරගෙන, තවදුරටත් මේ Dummy APIs එක්ක ටිකක් වැඩ කරලා බලන්න. ඒක ඔයාලගේ දැනුම තවත් වැඩි කරගන්න උදව් වෙයි.

මතක තියාගන්න, Software Engineering කියන්නේ නිරන්තරයෙන් ඉගෙන ගන්න ඕන Field එකක්. මේ වගේ දේවල් ප්‍රායෝගිකව කරලා බලන එක හරිම වැදගත්. මේ Blog Post එක ගැන ඔයාලගේ අදහස්, ප්‍රශ්න පහළින් Comment කරන්න. ඔයාලත් මේ වගේ APIs එක්ක වැඩ කරපු අත්දැකීම් තියෙනවා නම්, ඒවත් අපිත් එක්ක බෙදාගන්න. තවත් මේ වගේ වැදගත් Blog Post එකකින් හමුවෙමු!