By Thisara Priyamal — 15 Aug 2025

REST API මූලික කරුණු සිංහලෙන්: ආරම්භක මාර්ගෝපදේශය | SC Guide

හැඳින්වීම: අපේ Digital ලෝකයේ 'නොපෙනෙන පාලම'

ඉතින් කොහොමද යාළුවනේ? අද අපි කතා කරන්න යන්නේ ඔයාලා හැමෝම දිනපතා භාවිත කරන Apps සහ Websites වල පිටිපස්සේ තියෙන හරිම වැදගත් තාක්ෂණයක් ගැන. ඔබ කවදා හෝ සිතුවාද Facebook එකේ feed එක refresh කරනකොට, නැත්නම් online store එකකින් භාණ්ඩයක් මිලදී ගන්නකොට, මේ දත්ත කොහොමද එක තැනකින් තව තැනකට යන්නේ කියලා?

සරලව කිව්වොත්, මේ හැමදේකටම පිටිපස්සේ ඉන්නේ APIs (Application Programming Interfaces). මේවා කියන්නේ විවිධ software එකිනෙකාට කතා කරන, දත්ත හුවමාරු කරගන්න අවස්ථාව සලසන නීති රීති සහ ප්‍රොටෝකෝල සමූහයක්. මේ අතරින් REST API කියන්නේ මේ දවස්වල Software Development ක්ෂේත්‍රයේ බහුලවම භාවිත වන, හරිම බලවත් සහ වැදගත් තාක්ෂණයක්. ඔබ නවීන Web Development, Mobile App Development, Cloud Computing, හෝ Data Science වැනි ක්ෂේත්‍රයක ඉන්නවා නම්, REST APIs ගැන හොඳ අවබෝධයක් තිබීම අත්‍යවශ්‍යයි.

මේ SC Guide එකෙන් අපි REST API යනු කුමක්ද, එය ක්‍රියා කරන ආකාරය, එහි මූලික සංකල්ප, සහ ප්‍රායෝගික උදාහරණයක් හරහා එය භාවිතා කරන ආකාරය සරලව සහ පැහැදිලිව සිංහලෙන් සාකච්ඡා කරනවා. ඉතින් අපි පටන් ගමු!

1. REST API යනු කුමක්ද? සරලව තේරුම් ගනිමු

මුලින්ම, API එකක් කියන්නේ මොකක්ද කියලා පොඩ්ඩක් බලමු. හිතන්නකෝ, ඔබ restaurant එකකට යනවා. Menu එක බලාගෙන ඔබට ඕනෑම කෑමක් Order කරනවා. ඔබ කෙලින්ම කුස්සියට ගිහින් කෑම හදන්නේ නැහැ නේද? ඔබ waiter ට කියනවා, ඔහු ඒක කුස්සියට කියලා කෑම හදලා ඔබට ගෙනත් දෙනවා. මෙතනදී waiter තමයි API එක. ඔහු ඔබ (Client) සහ කුස්සිය (Server) අතර සම්බන්ධය ඇති කරනවා.

දැන් REST API කියන්නේ REST (Representational State Transfer) කියන architectural style එක පාවිච්චි කරලා හදන API එකක්. මේක Web Services නිර්මාණය කරන්න භාවිතා කරන ක්‍රමවේදයක්. REST APIs සාමාන්‍යයෙන් HTTP (Hypertext Transfer Protocol) මත පදනම් වෙලා තමයි වැඩ කරන්නේ. Web එකේ දත්ත හුවමාරු කරන්න තියෙන ප්‍රධානම ක්‍රමය HTTP නිසා, REST API වලට ලොකු ජනප්‍රියත්වයක් ලැබිලා තියෙනවා.

REST හි මූලික මූලධර්ම (Core Principles of REST):

REST API එකක් හොඳට තේරුම් ගන්න නම්, ඒකේ තියෙන මූලික මූලධර්ම ටික දැනගන්න එක වැදගත්.

Client-Server Architecture: මෙහිදී Client (ඔබේ Web browser, Mobile App වගේ) සහ Server (data තියෙන තැන) කියන දෙක එකිනෙකින් සම්පූර්ණයෙන්ම වෙන් වෙලා වැඩ කරනවා. ඒ කියන්නේ Client එකට Server එක ගැන වැඩිය හිතන්න අවශ්‍ය නැහැ. Server එකටත් Client එක ගැන වැඩිය හිතන්න අවශ්‍ය නැහැ. දෙගොල්ලන්ටම තමන්ගේ වැඩේට විතරක් අවධානය දෙන්න පුළුවන්.
Stateless: මේක හරිම වැදගත් සංකල්පයක්. හැම Client request එකක්ම Server එකට ස්වාධීනයි. ඒ කියන්නේ, Server එක කලින් request එකකින් Client ගැන කිසිම තොරතුරක් මතක තියාගන්නේ නැහැ. හැම request එකකටම අවශ්‍ය හැම තොරතුරක්ම අඩංගු වෙන්න ඕනේ. (උදාහරණයක් විදිහට, ඔබට යාලුවෙක් එක්ක කතා කරන්න හැම වෙලාවෙම අලුතෙන් මුල ඉදන්ම විස්තර කියන්න වෙනවා වගේ. කලින් කිව්ව ඒවා මතක තියාගන්නේ නැහැ.)
Cacheable: Server එකෙන් එන responses (ප්‍රතිචාර) Client එකට හෝ අතරමැදි servers (proxies) වලට cache කරන්න පුළුවන්. ඒ කියන්නේ, එකම request එකක් ආයෙත් ආවොත්, Server එකට යන්නෙ නැතුව cache එකෙන් data දෙන්න පුළුවන්. මේකෙන් performance වැඩි වෙනවා.
Layered System: Client එකට Server එකට කෙලින්ම සම්බන්ධ වෙන්න පුළුවන් වගේම, අතරමැදි servers (load balancers, proxies) හරහාත් සම්බන්ධ වෙන්න පුළුවන්. මේකෙන් scalability සහ security වැඩි වෙනවා.
Uniform Interface: මේක REST හි හදවතයි. ඒ කියන්නේ, Client සහ Server අතර සම්බන්ධය සරල සහ එකම විදිහකට පවත්වාගෙන යනවා. මේකට ප්‍රධාන දේවල් 4ක් තියෙනවා:
- Resources: REST API එකකදී හැමදේම Resource එකක් විදිහට තමයි සලකන්නේ. (උදා: users, products, orders). හැම resource එකකටම unique URL (URI - Uniform Resource Identifier) එකක් තියෙනවා.
- Representation: Client එකක් resource එකක් ඉල්ලනකොට, Server එක ඒකේ representation එකක් යවනවා. මේක JSON, XML වගේ formats වලින් වෙන්න පුළුවන්. JSON තමයි දැන් බහුලවම පාවිච්චි වෙන්නේ.
- Self-descriptive Messages: Client එකෙන් Server එකට යන හැම message එකක්ම තමන්ට අවශ්‍ය දේ පැහැදිලිව කියනවා. Server එකෙන් එන හැම message එකකුත් තමන් මොකක්ද ගෙනාවේ කියලා පැහැදිලි කරනවා.
- Hypermedia as the Engine of Application State (HATEOAS): මේක ටිකක් Advanced concept එකක්. සරලව කිව්වොත්, Server එකෙන් එන response එකේම ඊළඟට කරන්න පුළුවන් දේවල් (links) අඩංගු වෙනවා. (අපි මේ ගැන මෙතනදී ගැඹුරින් සාකච්ඡා කරන්නේ නැහැ, මූලික අවබෝධය සඳහා.)

2. HTTP Methods සහ ඒවායේ භාවිතය: REST API එකට නියෝග දෙමු!

REST API එකකදී Client එකක් Server එකට දත්ත ඉල්ලන්න, යවන්න, වෙනස් කරන්න, මකන්න වගේ දේවල් කරන්න HTTP Methods නැත්නම් HTTP Verbs පාවිච්චි කරනවා. මේවා තමයි සාමාන්‍යයෙන් භාවිතා වන ප්‍රධාන Methods:

DELETE (Deleting Data):මේකෙන් කරන්නේ Server එකේ තියෙන data එකක් මකලා දාන එක.

DELETE /users/123    // ID 123 තියෙන user කෙනෙක්ව delete කරන්න

PATCH (Updating Data / Partial Update):PUT වගේම update කරන්න තමයි. හැබැයි මේකෙන් කරන්නේ resource එකක කොටසක් (ඒ කියන්නේ එක Field එකක් වගේ) update කරන එක. හැම වෙලාවෙම PATCH support කරන්නේ නැහැ.

PATCH /users/123     // ID 123 තියෙන user ගේ email එක විතරක් update කරන්න
Request Body: { "email": "[email protected]" }

PUT (Updating Data / Full Replacement):මේකෙන් කරන්නේ Server එකේ තියෙන data එකක් සම්පූර්ණයෙන්ම update කරන එක. (උදා: user කෙනෙක්ගේ සම්පූර්ණ profile එකම වෙනස් කරනවා වගේ). මේකෙන් යවන්නේ resource එකේ අලුත්, සම්පූර්ණ version එක.

PUT /users/123       // ID 123 තියෙන user ගේ data සම්පූර්ණයෙන් update කරන්න
Request Body: { "name": "Kamal", "email": "[email protected]", "age": 30 }

POST (Creating Data):මේකෙන් කරන්නේ Server එකේ අලුත් data එකක් හදන එක. (උදා: අලුත් Facebook post එකක් දානවා වගේ, online store එකක අලුත් product එකක් add කරනවා වගේ).

POST /users          // අලුත් user කෙනෙක් හදන්න
Request Body: { "name": "Nimal", "email": "[email protected]" }

GET (Retrieving Data):මේකෙන් කරන්නේ Server එකෙන් data එකක් ගන්න එක. (උදා: website එකක post එකක් බලනවා වගේ, online store එකක product list එකක් බලනවා වගේ). මේකෙන් Server එකේ කිසිම වෙනසක් වෙන්නේ නැහැ.

GET /users           // හැම user කෙනෙක්ම ගන්න
GET /users/123       // ID 123 තියෙන user කෙනෙක් ගන්න
GET /products/category/electronics // 'electronics' category එකේ products ගන්න

3. REST API නිර්මාණය කිරීමේදී සහ භාවිත කිරීමේදී වැදගත් දේවල්

හොඳ REST API එකක් හදනකොට හෝ පාවිච්චි කරනකොට මේ දේවල් ගැන සැලකිලිමත් වෙන එක හරිම වැදගත්.

3.1. Resources සහ URLs (Endpoint Naming Conventions)

REST API එකකදී හැමදේම resource එකක් විදිහට අපි සලකනවා කිව්වනේ. ඒ resources වලට දෙන URL (හෝ Endpoint) හරිම පැහැදිලි වෙන්න ඕනේ. පොදු නීති කිහිපයක් මෙන්න:

නාම පද (Nouns) භාවිතා කරන්න: ක්‍රියා පද (verbs) වෙනුවට නාම පද භාවිතා කරන්න. (e.g., /users මිසක් /getUsers නොවෙයි).
බහු වචන (Plurals) භාවිතා කරන්න: සාමාන්‍යයෙන් resource collection එකක් දක්වන්න බහු වචන භාවිතා කරනවා. (e.g., /products, /orders).
හැකි තරම් සරල වෙන්න: URL එකේ තේරුම එක බැලූ බැල්මට තේරෙන්න ඕනේ.

උදාහරණ:

සියලුම users ලබා ගැනීමට: GET /users
එක් user කෙනෙක් ලබා ගැනීමට: GET /users/{id} (මෙහි {id} යනු user ගේ ID එක)
අලුත් product එකක් එකතු කිරීමට: POST /products
order එකක status එක update කිරීමට: PUT /orders/{id}/status

3.2. HTTP Status Codes

ඔබ Server එකකට request එකක් යැව්වම, Server එකෙන් response එකක් එනවා. මේ response එකත් එක්ක HTTP Status Code එකක් එනවා. මේකෙන් කියවෙන්නේ ඔබේ request එක සාර්ථකද, නැත්නම් මොකක් හරි ගැටලුවක්ද කියලා. මේවා ගැන අවබෝධයක් තියෙන එක request එක සාර්ථකද කියලා බලන්න වැදගත්.

2xx (Success): Request එක සාර්ථකව සම්පූර්ණ වුණා. (හොඳයි!).
- 200 OK: සාමාන්‍යයෙන් සාර්ථක request වලට (GET, PUT, DELETE)
- 201 Created: POST request එකකින් අලුතින් resource එකක් හැදුවම.
- 204 No Content: DELETE request එකකින් සාර්ථකව resource එකක් මකලා, response body එකේ කිසිම data එකක් නැත්නම්.
4xx (Client Error): Request එකේ ගැටලුවක් තිබුණා.
- 400 Bad Request: Client එකෙන් යැව්ව request එකේ වැරදි තිබුණා. (Data format එක වැරදියි වගේ).
- 401 Unauthorized: Client එකට මේ request එක කරන්න අවසර නෑ. (login වෙලා නෑ වගේ).
- 403 Forbidden: Client එකට අවසර තිබ්බත්, මේ විශේෂ resource එකට access කරන්න බෑ.
- 404 Not Found: ඉල්ලපු resource එක Server එකේ නැහැ.
5xx (Server Error): Server එකේ ගැටලුවක් තිබුණා.
- 500 Internal Server Error: Server එකේ ඇතුළේ මොකක් හරි වැරැද්දක් වුණා.
- 503 Service Unavailable: Server එකට දැනට request එක handle කරන්න බෑ (busy වගේ).

3.3. Data Format: JSON

REST API වල දත්ත හුවමාරු කරන්න බහුලවම භාවිතා කරන්නේ JSON (JavaScript Object Notation) කියන format එක. මේක කියවන්න සහ ලියන්න පහසුයි, ඒ වගේම JavaScript වලට කෙලින්ම වගේ convert කරන්න පුළුවන්. XML වලට වඩා මේක ජනප්‍රියයි, මොකද මේක සැහැල්ලු (lightweight) නිසා.

JSON උදාහරණයක්:

{
  "id": 1,
  "title": "අපේ පළමු API Post එක",
  "body": "මේක තමයි REST API ගැන ලියපු අපේ පළමු Post එකේ Body එක.",
  "userId": 1
}

4. ප්‍රායෝගික උදාහරණයක්: JavaScript සහ Public API එකක්

දැන් අපි බලමු ඇත්තටම REST API එකක් JavaScript වලින් කොහොමද පාවිච්චි කරන්නේ කියලා. අපි මේකට JSONPlaceholder කියන Free Fake REST API එක පාවිච්චි කරනවා. මේකෙන් අපිට test කරන්න Posts, Users වගේ data ගන්න පුළුවන්.

අපි මේ උදාහරණයෙන් GET request එකක් කරලා, පළමු Post එකේ විස්තර ලබාගන්නවා.

// HTML document එක load වුනාම මේ function එක execute කරන්න.
document.addEventListener('DOMContentLoaded', () => {
  // Public API එකකින් data GET කරමු
  // අපි JSONPlaceholder API එකේ /posts/1 කියන endpoint එකට request එක යවනවා
  fetch('https://jsonplaceholder.typicode.com/posts/1')
    .then(response => {
      // ලැබුණු HTTP response එක සාර්ථකද (status code 200-299 අතරද) කියලා බලනවා
      if (!response.ok) {
        // response එක සාර්ථක නැත්නම් error එකක් throw කරනවා
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      // response එක JSON format එකට convert කරනවා
      // .json() method එක asynchronous නිසා, මේකත් Promise එකක් return කරනවා
      return response.json();
    })
    .then(data => {
      // JSON බවට convert කරපු data console එකේ print කරනවා
      console.log('ලැබුණු Post එක:', data);

      // ඔබට මේ data HTML elements වලටත් එකතු කරන්න පුළුවන්
      // උදාහරණයක් විදිහට, HTML එකේ id="post-title" සහ id="post-body" තියෙන elements වලට data එකතු කරමු
      const postTitleElement = document.getElementById('post-title');
      const postBodyElement = document.getElementById('post-body');

      if (postTitleElement) {
        postTitleElement.innerText = data.title;
      }
      if (postBodyElement) {
        postBodyElement.innerText = data.body;
      }

      // ඔබට අවශ්‍ය නම් තවත් data elements වලට එකතු කරන්න පුළුවන්
      // console.log(data.userId);
    })
    .catch(error => {
      // API call එකේදී error එකක් ආවොත් මේ catch block එක execute වෙනවා
      console.error('API call එකේදී Error එකක් සිදුවිය:', error);
      // User ට පෙන්වන්න පුළුවන් error message එකක් display කරන්න
      const errorElement = document.getElementById('error-message');
      if (errorElement) {
        errorElement.innerText = 'දත්ත ලබාගැනීමේදී දෝෂයක් සිදුවිය. කරුණාකර නැවත උත්සාහ කරන්න.';
      }
    });
});

මේ Code එකෙන් මොකද වෙන්නේ?

document.addEventListener('DOMContentLoaded', ...): මේකෙන් කරන්නේ, අපේ HTML document එක සම්පූර්ණයෙන් load වුණාට පස්සේ, ඇතුළේ තියෙන code එක execute කරන්න සලස්වන එක.
fetch('https://jsonplaceholder.typicode.com/posts/1'): මේක තමයි API call එක. JavaScript වල built-in fetch API එක පාවිච්චි කරලා, දීලා තියෙන URL එකට GET request එකක් යවනවා. මේක Promise එකක් return කරනවා.
.then(response => { ... }): Request එකට Server එකෙන් response එකක් ආවම මේ කොටස execute වෙනවා. මුලින්ම response.ok (status code 200-299 අතරද) කියලා බලලා, successful ද කියලා check කරනවා. සාර්ථක නම් response.json() කියලා response body එක JSON බවට convert කරනවා.
.then(data => { ... }): response.json() එකෙන් return කරන Promise එක සාර්ථක වුණාම, JSON data එක මේ data කියන variable එකට එනවා. ඊට පස්සේ අපිට ඒ data එක console එකේ print කරන්න, නැත්නම් HTML එකේ element වලට එකතු කරන්න වගේ දේවල් කරන්න පුළුවන්.
.catch(error => { ... }): API call එකේදී හෝ data process කරනකොට මොකක් හරි error එකක් ආවොත් (network error, invalid JSON වගේ), මේ කොටස execute වෙනවා. මේකෙන් අපිට user ට error message එකක් පෙන්වන්න පුළුවන්.

මේ code එක වැඩ කරනවා බලන්න, ඔබට මේ වගේ සරල HTML file එකක් හදන්න පුළුවන්:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>REST API Demo</title>
</head>
<body>
    <h1>අපේ පළමු API Post එක</h1>
    <h2 id="post-title">Loading...</h2>
    <p id="post-body">Loading post content...</p>
    <p id="error-message" style="color: red;"></p>

    <script src="./app.js"></script> <!-- ඔබේ JavaScript file එක මෙතන link කරන්න -->
</body>
</html>

මේ HTML file එක index.html කියලා save කරලා, ඉහත JavaScript code එක app.js කියලා ඒකම folder එකේ save කරලා, index.html එක browser එකේ open කරලා බලන්න. ඔබට JSONPlaceholder එකෙන් data ලැබෙනවා දකින්න පුළුවන්.

නිගමනය: REST API, ඔබේ Digital ගමනේ අත්‍යවශ්‍ය හවුල්කරුවෙක්!

දැන් ඔයාට REST API කියන්නේ මොකක්ද කියලා හොඳ අවබෝධයක් ඇති කියලා මම හිතනවා. ඒ වගේම, එය Software Development වලදී කොච්චර වැදගත්ද කියලත් තේරෙන්න ඇති. Client එකක් සහ Server එකක් අතර සරලව, කාර්යක්ෂමව සහ නම්‍යශීලීව දත්ත හුවමාරු කරගැනීමට REST API අපිට අවස්ථාව සලසනවා. Client-Server architecture, Statelessness, Cacheability, Layered Systems, සහ Uniform Interface වැනි මූලික මූලධර්ම තේරුම් ගැනීමෙන් ඔබට වඩා හොඳ APIs නිර්මාණය කිරීමට හෝ පවතින API භාවිතා කිරීමට හැකියාව ලැබෙනවා.

අද අපි HTTP Methods (GET, POST, PUT, DELETE) සහ ඒවායේ භාවිතය, URL Naming conventions, HTTP Status Codes, සහ JSON දත්ත format එක ගැනත් සාකච්ඡා කළා. අවසාන වශයෙන්, JavaScript fetch API එක පාවිච්චි කරලා, Public API එකකින් data ලබාගන්න විදිහත් අපි ප්‍රායෝගිකව දැක්කා. මේවා තමයි REST API ලෝකයට පිවිසෙන ඔබට අත්‍යවශ්‍ය වන මූලිකම කරුණු.

මේ දැනුමෙන් සන්නද්ධ වෙලා, ඔබත් මේ වගේ Public API එකක් භාවිතා කරලා පොඩි Web application එකක් හදන්න උත්සාහ කරන්න. ඔබේ අත්දැකීම්, ගැටලු හෝ අදහස් පහතින් comment කරන්න! ඔබේ අදහස් අපිට ගොඩක් වටිනවා. මේ වගේ තවත් Guides ඕනිනම්, අපිට කියන්න!

Happy Coding, යාළුවනේ!