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

Demystifying REST APIs: A Practical Guide for Beginners SC Guide

කොහොමද යාළුවනේ! අද අපි කතා කරන්න යන්නේ ඔයාලා හැමෝටම ගොඩක් වැදගත් වෙන, ඒ වගේම Web Development ලෝකයේ අනිවාර්යයෙන්ම දැනගෙන ඉන්න ඕන කරන දෙයක් ගැන. ඒ තමයි REST APIs (Representational State Transfer Application Programming Interfaces). මේ වචන ටික ඇහුවම සමහර විට ඔයාලට ටිකක් සංකීර්ණ වෙන්න පුළුවන්, ඒත් අද අපි මේක හරිම සරලව, උදාහරණ එක්ක තේරුම් ගමු.

ඔයාලා කවදා හරි කල්පනා කරලා තියෙනවද, අපි ෆේස්බුක් එකේ පෝස්ට් එකක් දානකොට, නැත්නම් යූටියුබ් එකේ වීඩියෝ එකක් බලනකොට, මේ ඩේටා ඔක්කොම server එකට ගිහින් එන්නේ කොහොමද කියලා? ඒ හැමදේම පිටිපස්සේ ඉන්නේ මේ APIs තමයි. API එකක් කියන්නේ විවිධ software applications වලට එකිනෙකා එක්ක කතා බස් කරන්න උදව් කරන පාලමක් වගේ දෙයක්. ඒ අතරින් REST APIs කියන්නේ අද දවසේ ගොඩක් ජනප්‍රිය, ව්‍යාප්ත වෙලා තියෙන ක්‍රමවේදයක්.

මේ blog post එකෙන් අපි REST APIs වල මූලික සංකල්ප, ඒවා වැඩ කරන ආකාරය, HTTP Methods, Endpoints සහ JSON වැනි ප්‍රධානම දේවල් ගැන විස්තරාත්මකව කතා කරනවා. ඒ වගේම ප්‍රායෝගික උදාහරණයක් හරහා REST API එකක් එක්ක වැඩ කරන්නේ කොහොමද කියලත් අපි ඉගෙන ගමු. එහෙනම්, අපි පටන් ගමු නේද?

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

මුලින්ම බලමු API එකක් කියන්නේ මොකක්ද කියලා. API කියන්නේ Application Programming Interface එකට. හරිම සරලව කිව්වොත්, software දෙකකට එකිනෙකා එක්ක කතා කරන්න උදව් කරන මෙවලමක්. අපි Google Maps API එක පාවිච්චි කරලා අපේ website එකට map එකක් එකතු කරනවා වගේ. අපි ඒ map එක හදන්නේ නැහැ, Google එකෙන් දීලා තියෙන පහසුකම් පාවිච්චි කරනවා.

දැන් බලමු REST කියන්නේ මොකක්ද කියලා. REST කියන්නේ Representational State Transfer. මේක APIs හදනකොට follow කරන්න පුළුවන් architectural style එකක්. Roy Fielding කියන කෙනා තමයි මේ concept එක මුලින්ම ඉදිරිපත් කළේ. REST APIs හදනකොට මේ principles ටික follow කරන්න ඕනේ:

• Client-Server Architecture: Client එකයි (අපේ browser එක වගේ) server එකයි (ඩේටා තියෙන තැන) වෙන් වෙලා වැඩ කරනවා. ඒ දෙක අතර සම්බන්ධයක් තියෙන්නේ ඉල්ලීම් සහ ප්‍රතිචාර හරහා විතරයි.
• Statelessness: මේක ගොඩක් වැදගත්. Server එකට client එකේ previous request එක ගැන කිසිම මතකයක් නැහැ. හැම request එකක්ම අලුත් එකක් විදියට server එක සලකනවා. හැම request එකකම ඒකට අවශ්‍ය හැම තොරතුරක්ම අඩංගු වෙන්න ඕනේ.
• Cacheable: Responses වල cache කරන්න පුළුවන්ද බැරිද කියලා සඳහන් කරන්න පුළුවන්. ඒකෙන් performance එක වැඩි වෙනවා.
• Layered System: Client එකට server එක කෙලින්ම සම්බන්ධ වෙලාද, නැත්නම් ඒ අතර proxy servers, load balancers වගේ දේවල් තියෙනවද කියලා දැනගන්න අවශ්‍ය නැහැ.
• Uniform Interface: මේක REST වල ප්‍රධානම constraint එකක්. API එක consistent වෙන්න ඕනේ. ඒ කියන්නේ resources හඳුනාගන්න, ඒවාට access කරන්න එකම විදියක් තියෙන්න ඕනේ.

හරිම සරල උදාහරණයක් කියනවා නම්, REST API එකක් කියන්නේ අපි restaurant එකකට ගිහින් waiter කෙනෙක්ට order එකක් දානවා වගේ. අපි order එක දානවා (request එක), waiter ඒක kitchen එකට දෙනවා, kitchen එකෙන් කෑම එක හදලා දෙනවා (response එක). මෙතන waiter කියන්නේ API එකට. අපි kitchen එකට කෙලින්ම කතා කරන්නේ නැහැ, waiter හරහා තමයි කතා කරන්නේ.

HTTP Methods සහ Endpoints (HTTP Methods and Endpoints)

REST APIs communicate වෙන්න HTTP (Hypertext Transfer Protocol) පාවිච්චි කරනවා. අපි web browser එකේ URL එකක් ගහලා website එකක් බලනකොටත් මේ HTTP තමයි වැඩ කරන්නේ. HTTP වල Methods කිහිපයක් තියෙනවා, ඒවා REST APIs වලදී operations විදියට පාවිච්චි කරනවා. මේවා තමයි ප්‍රධානම HTTP Methods:

• GET: Server එකෙන් data ගන්න (retrieve) පාවිච්චි කරනවා. Database එකෙන් තොරතුරු කියවන්න වගේ දෙයකට.
• POST: අලුත් data server එකට යවන්න (create) පාවිච්චි කරනවා. Form එකක් submit කරලා අලුත් user කෙනෙක් create කරනවා වගේ.
• PUT: තියෙන data එකක් update කරන්න (complete replacement) පාවිච්චි කරනවා. User කෙනෙකුගේ හැම විස්තරයක්ම වෙනස් කරනවා වගේ.
• PATCH: තියෙන data එකක කොටසක් විතරක් update කරන්න (partial modification) පාවිච්චි කරනවා. User කෙනෙකුගේ email එක විතරක් වෙනස් කරනවා වගේ.
• DELETE: Server එකෙන් data එකක් අයින් කරන්න (delete) පාවිච්චි කරනවා.

දැන් බලමු Endpoint එකක් කියන්නේ මොකක්ද කියලා. Endpoint එකක් කියන්නේ server එකේ තියෙන resource එකක් හඳුනාගන්න පාවිච්චි කරන URL එකක්. උදාහරණයක් විදියට:

• /users: හැම user කෙනෙක්ම.
• /users/123: ID එක 123 වෙන user.
• /products/456/reviews: Product 456 ට අදාළ reviews.

මේ HTTP Method එකයි, Endpoint එකයි එකතු වෙලා තමයි API request එකක් හදන්නේ. පහත වගුවේ ඒක පැහැදිලිව පේනවා ඇති:

GET Request එකක උදාහරණයක් (Example of a GET Request)

අපි cURL (command line tool) පාවිච්චි කරලා GET request එකක් කරන්නේ කොහොමද කියලා බලමු. මේකෙන් public API එකකින් user data ටිකක් fetch කරගන්න පුළුවන්:

curl -X GET "https://jsonplaceholder.typicode.com/users/1"

මේ command එක රන් කරාම ඔයාට ID 1 තියෙන user ගේ ඩේටා JSON format එකෙන් ලැබේවි.

JSON - Data Format එක (JSON - The Data Format)

REST APIs එක්ක වැඩ කරනකොට ඔයාලට ගොඩක් වෙලාවට හම්බවෙන data format එකක් තමයි JSON (JavaScript Object Notation). මේක මිනිස්සුන්ට කියවන්නත්, machines වලට parse කරන්නත් පහසු, සැහැල්ලු data-interchange format එකක්. JSON කියන්නේ JavaScript වලින් ආපු එකක් වුණත්, දැන් හැම programming language එකකම වගේ JSON එක්ක වැඩ කරන්න පුළුවන්. ඒක universally accepted format එකක්.

JSON data නිරූපණය වෙන්නේ key-value pairs සහ arrays විදියට. අපි උදාහරණයක් බලමු:

{
  "name": "Kasun Perera",
  "age": 30,
  "isStudent": false,
  "courses": [
    "Software Engineering",
    "Data Science",
    "Cloud Computing"
  ],
  "address": {
    "street": "123 Main Street",
    "city": "Colombo",
    "zipCode": "00100"
  }
}

මේ උදාහරණයේ තියෙන JSON object එකක name, age, isStudent වගේ key-value pairs තියෙනවා. courses කියන්නේ array එකක්. ඒ වගේම address කියන්නේ තව nested JSON object එකක්.

JSON වල මේ simplicity එක නිසා තමයි REST APIs වලදී data යවන්න සහ ගන්න මේක ගොඩක් ජනප්‍රිය වෙලා තියෙන්නේ. ඒක XML වගේ තවත් data format වලට වඩා සැහැල්ලුයි, ඒ වගේම web browsers වල JavaScript එක්ක කෙලින්ම වැඩ කරන්න පුළුවන්.

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

දැන් අපි බලමු JavaScript වල fetch API එක පාවිච්චි කරලා REST API එකක් එක්ක වැඩ කරන්නේ කොහොමද කියලා. අපි dummy API එකක් වන JSONPlaceholder පාවිච්චි කරමු. මේකෙන් අපිට fake data එක්ක GET, POST, PUT, DELETE වගේ requests practice කරන්න පුළුවන්.

1. සියලුම Post ගන්න (GET all posts)

මේ code එකෙන් JSONPlaceholder එකේ තියෙන හැම post එකක්ම fetch කරගන්න පුළුවන්. අපි browser එකේ console එකේ මේක රන් කරලා බලමු.

fetch('https://jsonplaceholder.typicode.com/posts')
  .then(response => response.json()) // Response එක JSON විදියට parse කරනවා
  .then(json => console.log(json))   // ලැබුණු JSON data එක console එකේ පෙන්වනවා
  .catch(error => console.error('Error fetching posts:', error)); // Error එකක් ආවොත් handle කරනවා

2. අලුත් Post එකක් දාන්න (POST a new post)

දැන් අපි POST request එකක් කරලා අලුත් post එකක් create කරමු. මේ request එකේදී අපි body එකේ JSON data එකක් යවනවා, ඒ වගේම Content-Type header එක application/json විදියට set කරන්න ඕනේ, server එකට data type එක කියන්න.

fetch('https://jsonplaceholder.typicode.com/posts', {
  method: 'POST', // HTTP Method එක POST විදියට සකසනවා
  body: JSON.stringify({
    title: 'Hello REST API',
    body: 'This is my first post using REST API in Sinhala!',
    userId: 1,
  }),
  headers: {
    'Content-type': 'application/json; charset=UTF-8',
  },
})
  .then((response) => response.json())
  .then((json) => console.log(json))
  .catch(error => console.error('Error creating post:', error));

මේ code එක රන් කරාම, JSONPlaceholder එකෙන් අපිට unique ID එකක් එක්ක අලුතින් create කරපු post එකේ object එකක් response එක විදියට ලැබේවි. (මේක dummy API එකක් නිසා ඇත්තටම data save වෙන්නේ නැහැ, නමුත් response එකෙන් successful creation එකක් පෙන්නනවා).

3. තියෙන Post එකක් Update කරන්න (PUT/PATCH an existing post)

දැන් අපි තියෙන post එකක් update කරන්නේ කොහොමද කියලා බලමු. PUT එකෙන් සම්පූර්ණ resource එකම replace කරනවා, PATCH එකෙන් කොටසක් විතරක් update කරනවා.

// PUT example (complete replacement)
fetch('https://jsonplaceholder.typicode.com/posts/1', {
  method: 'PUT',
  body: JSON.stringify({
    id: 1,
    title: 'Updated Post Title',
    body: 'This post has been fully updated.',
    userId: 1,
  }),
  headers: {
    'Content-type': 'application/json; charset=UTF-8',
  },
})
  .then((response) => response.json())
  .then((json) => console.log(json))
  .catch(error => console.error('Error updating post:', error));

4. Post එකක් Delete කරන්න (DELETE a post)

අවසාන වශයෙන්, post එකක් delete කරන්නේ කොහොමද කියලා බලමු.

fetch('https://jsonplaceholder.typicode.com/posts/1', {
  method: 'DELETE',
})
  .then((response) => response.json()) // DELETE request එකකටත් response එකක් එන්න පුළුවන්
  .then((json) => console.log(json)) // සාමාන්‍යයෙන් හිස් object එකක් හෝ success message එකක්
  .catch(error => console.error('Error deleting post:', error));

මේ examples ඔයාලට REST APIs එක්ක interact වෙන්න හොඳ අදහසක් ලබා දෙනවා කියලා හිතනවා.

නිගමනය (Conclusion)

ඉතින් යාළුවනේ, අපි මේ blog post එකෙන් REST APIs කියන්නේ මොකක්ද, ඒවා වැඩ කරන්නේ කොහොමද, HTTP Methods, Endpoints, JSON වගේ core concepts ගැන ගොඩක් දේවල් ඉගෙන ගත්තා. ඒ වගේම ප්‍රායෝගික උදාහරණ හරහා JavaScript වල fetch API එක පාවිච්චි කරලා REST API එකක් එක්ක වැඩ කරන හැටිත් අපි බැලුවා.

නූතන web development වලදී REST APIs අවබෝධ කරගැනීම අතිශයින්ම වැදගත්. මොකද, අද දවසේ හැම application එකක්ම වගේ data හුවමාරු කරගන්න මේ concept එක පාවිච්චි කරනවා. Frontend (React, Vue, Angular) හෝ Backend (Node.js, Python, Java) ඕනෑම developer කෙනෙක්ට මේ දැනුම අනිවාර්යයෙන්ම අවශ්‍යයි.

දැන් ඔයාලට පුළුවන් මේක ප්‍රායෝගිකව අත්හදා බලන්න. තවදුරටත් JSONPlaceholder වගේ dummy API එකක් පාවිච්චි කරලා විවිධ requests කරලා බලන්න. තවදුරටත් error handling, authentication, pagination වගේ දේවල් ගැනත් ඔයාලට ඉගෙන ගන්න පුළුවන්.

ඔයාලගේ අත්දැකීම්, ප්‍රශ්න, නැත්නම් මේ ගැන අලුතින් ඉගෙනගත්ත දේවල් පහළ comments අංශයේ සඳහන් කරන්න. මේ knowledge එක අනිත් අයත් එක්ක share කරගන්න අමතක කරන්න එපා. ජයවේවා!