REST APIs සරලව තේරුම් ගනිමු - SC Guide

ආයුබෝවන් යාළුවනේ!

අද අපි කතා කරන්න යන්නේ ඔයාලා හැමෝටම වැදගත් වෙන, Software Engineering ලෝකයේ නැතුවම බැරි දෙයක් ගැන – ඒ තමයි REST APIs. 'API' කිව්වම සමහරවිට ටිකක් අමුතු වචනයක් වගේ දැනෙන්න පුළුවන්. ඒත් බයවෙන්න එපා! අපි මේක ඉතාම සරලව, පහසුවෙන් තේරුම් ගන්න පුළුවන් විදියට කතා කරමු. මොකද, අද කාලේ ඔයාලා පාවිච්චි කරන ගොඩක් Apps, Websites පිටිපස්සේ මේ APIs තමයි වැඩ කරන්නේ.

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

REST APIs යනු කුමක්ද?

මුලින්ම බලමු මේ 'API' කියන්නේ මොකක්ද කියලා. API කියන්නේ Application Programming Interface එකට. සරලවම කිව්වොත්, ඒක එක Software එකකට තවත් Software එකක් එක්ක කතා කරන්න උදව් කරන 'සම්බන්ධකයක්' (connector) වගේ දෙයක්. හරියට, ඔයා Restaurant එකකට ගිහින් Order එකක් දෙනකොට Waiter කෙනෙක් ඉන්නවා වගේ. ඔයාට අවශ්‍ය දේ (තොරතුරු) Waiter (API) හරහා Kitchen (වෙනත් Software/Server) එකට යනවා, ඒ වගේම Kitchen එකෙන් සකස් කරපු දේ (Request එකට අදාළ Response එක) Waiter හරහා ඔයාට ලැබෙනවා.

දැන් එතකොට REST API කියන්නේ මොකක්ද? REST කියන්නේ Representational State Transfer කියන එකට. මේක විශේෂිත 'architectural style' එකක්. ඒ කියන්නේ, මේක Software Systems නිර්මාණය කරන්න පිළිපදින නීති රීති සහ මූලධර්ම Set එකක්. REST APIs නිර්මාණය කරලා තියෙන්නේ Web එකේ (HTTP) තියෙන හැකියාවන් උපරිමයෙන් ප්‍රයෝජනයට ගන්න. මේවා 'Stateless' වෙනවා. ඒ කියන්නේ, හැම Request එකක්ම ස්වාධීනව ක්‍රියා කරනවා. Server එකට කලින් ආපු Request එකක තොරතුරු මතක තියාගන්න ඕනේ නැහැ.

REST API එකක තියෙන ප්‍රධානම දේ තමයි 'Resources'. මේවා කියන්නේ අපිට ප්‍රවේශ වෙන්න පුළුවන් දත්ත වලට. උදාහරණයක් විදියට, users, products, orders වගේ දේවල්. මේ Resources වලට අපි ප්‍රවේශ වෙන්නේ Unique Resource Identifiers (URIs) නැත්නම් URLs හරහා.

අපි මේ Resources එක්ක වැඩ කරන්න HTTP Methods (verbs) පාවිච්චි කරනවා. මේවා තමයි:

• GET: Server එකෙන් දත්ත ලබා ගන්න.
• POST: Server එකට අලුත් දත්ත එකතු කරන්න.
• PUT: Server එකේ තියෙන දත්ත Update කරන්න (සම්පූර්ණයෙන්ම වෙනස් කරන්න).
• PATCH: Server එකේ තියෙන දත්ත Update කරන්න (කොටසක් විතරක් වෙනස් කරන්න).
• DELETE: Server එකෙන් දත්ත මකන්න.

සරල උදාහරණයක් බලමු:

• GET /api/products: හැම product එකක්ම ලබා ගන්න.
• GET /api/products/123: ID එක 123 වෙන product එක ලබා ගන්න.
• POST /api/products: අලුත් product එකක් එකතු කරන්න.
• PUT /api/products/123: ID එක 123 වෙන product එක update කරන්න.
• DELETE /api/products/123: ID එක 123 වෙන product එක මකන්න.

REST හි මූලික මූලධර්ම

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

• Client-Server Separation: Client (Browser, Mobile App) එක Server (API එක) එකෙන් වෙන් වෙලා තියෙන්න ඕනේ. දෙකටම තමන්ගේ වැඩේ විතරක් බලන්න පුළුවන් වෙන්න ඕනේ.
• Statelessness: කලින් කිව්වා වගේ, හැම Request එකක්ම තමන්ට අවශ්‍ය හැම තොරතුරක්ම අරන් එන්න ඕනේ. Server එකට කලින් Requests ගැන මතක තියාගන්න ඕනේ නැහැ.
• Cacheability: Client පැත්තට Response Cache කරන්න පුළුවන් වෙන්න ඕනේ. එතකොට නිතරම Server එකට Request යවන්න ඕනේ නැහැ. වේගය වැඩි වෙනවා.
• Layered System: API එකට Layer කිහිපයකින් සමන්විත වෙන්න පුළුවන් (e.g., Load Balancers, Proxies). Client එකට ඒ ගැන දැනගන්න ඕනේ නැහැ.
• Uniform Interface: මේක තමයි වැදගත්ම දේ. Standard Methods (GET, POST, etc.) සහ URIs පාවිච්චි කරන්න ඕනේ. HATEOAS (Hypermedia As The Engine Of Application State) කියන එකෙනුත් කියවෙන්නේ API Response එකේදී ඊළඟට කරන්න පුළුවන් දේවල් (links) ගැනත් තොරතුරු දෙන්න ඕනේ කියන එක. ඒක ටිකක් Advanced Level එකක්, ඒත් දැනට මේකෙන් කියවෙන්නේ API එකක් හරහා යනකොට හැමදේම Consistent විදියට තියෙන්න ඕනේ කියන එක.

REST APIs සමඟ වැඩ කරන්නේ කෙසේද?

REST API එකක් එක්ක කතා කරනවා කියන්නේ Client එකක් Server එකකට HTTP Request එකක් යවනවා, ඊට පස්සේ Server එකෙන් HTTP Response එකක් එනවා. මේ Request එකයි Response එකයි අතර දත්ත හුවමාරු වෙන්නේ සාමාන්‍යයෙන් JSON (JavaScript Object Notation) Format එකෙන්. ඒක කියවන්නයි, ලියන්නයි පහසුයි.

අපි curl කියන Command Line Tool එක පාවිච්චි කරලා සරල උදාහරණයක් බලමු. මේකෙන් HTTP Requests යවන්න පුළුවන්.

1. GET Request එකක් යවන හැටි (දත්ත ලබා ගැනීම):

අපි හිතමු අපිට Posts ලැයිස්තුවක් ගන්න ඕනේ කියලා. Public API එකක් පාවිච්චි කරමු. JSONPlaceholder කියන්නේ Fake Online REST API එකක්. Testing වලට හොඳයි.

curl https://jsonplaceholder.typicode.com/posts

මේ Command එක දුන්නම ඔයාලට Posts ලැයිස්තුවක් JSON Format එකෙන් ලැබෙයි. (මේක Command Prompt/Terminal එකේ Run කරන්න).

2. POST Request එකක් යවන හැටි (අලුත් දත්ත එකතු කිරීම):

අලුත් Post එකක් Server එකට එකතු කරමු. මේකට Request Body එකකුත් යවන්න ඕනේ. ඒක තමයි අපි Server එකට දෙන්න යන දත්ත.

curl -X POST -H "Content-Type: application/json" -d '{"title": "My New Post", "body": "This is the content of my new post.", "userId": 1}' https://jsonplaceholder.typicode.com/posts

මෙතන:

• -X POST: කියන්නේ මේක POST Request එකක් කියලා.
• -H "Content-Type: application/json": අපි යවන දත්ත JSON Format එකේ කියලා Server එකට කියනවා.
• -d '...': අපි යවන්න යන දත්ත (Request Body) JSON Format එකෙන් දෙනවා.

මේක සාර්ථක වුනොත් ඔයාලට අලුත් Post එකේ ID එකත් එක්ක Response එකක් ලැබෙයි.

JavaScript (Browser එකකින්) හෝ Python වගේ Programming Languages වලින් මේ Requests යවන්න පුළුවන් Libraries තියෙනවා.

• JavaScript වලට fetch API එක නැත්නම් Axios වගේ Library එකක්.
• Python වලට requests Library එක.

ඒවා ගැන වෙනම Post එකක කතා කරමු.

හොඳම පුරුදු සහ පොදු වැරදි (Best Practices & Common Pitfalls)

හොඳ REST API එකක් හදනකොට හෝ පාවිච්චි කරනකොට මේ කරුණු ටික මතක තියාගන්න.

• API Versioning: ඔයාගේ API එක කාලයත් එක්ක වෙනස් වෙන්න පුළුවන්. ඒකට v1, v2 වගේ Versioning පාවිච්චි කරන්න. (e.g., /api/v1/products).
• Error Handling: API එකක වැරැද්දක් වුනොත් හරියට Status Codes (404 Not Found, 400 Bad Request, 500 Internal Server Error) එක්ක පැහැදිලි Error Message එකක් දෙන්න. Client එකට ඒක තේරුම් ගන්න පුළුවන් වෙන්න ඕනේ.
• Authentication & Authorization: හැමෝටම ඔයාගේ API එකට ප්‍රවේශ වෙන්න දෙන්න බැහැ. API Keys, OAuth 2.0 වගේ දේවල් පාවිච්චි කරලා ආරක්ෂා කරන්න.
• Rate Limiting: එක Client කෙනෙක්ට විනාඩියකට යවන්න පුළුවන් Request ගාන සීමා කරන්න. නැත්නම් ඔයාගේ Server එක Overload වෙන්න පුළුවන්.
• Documentation: ඔයාගේ API එක ගැන හොඳට Documentation කරන්න. ඒක Developers ලට පහසුවෙන් පාවිච්චි කරන්න පුළුවන් වෙනවා.

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

ඉතින් යාළුවනේ, මේ POST එකෙන් ඔයාලට REST APIs ගැන හොඳ මූලික අවබෝධයක් ලැබෙන්න ඇති කියලා හිතනවා. මේවා අද Web Development වලදී නැතුවම බැරි දෙයක්. ඔයාලා Front-end Developer කෙනෙක් වෙන්න බලාපොරොත්තු වුනත්, Back-end Developer කෙනෙක් වෙන්න බලාපොරොත්තු වුනත් මේ සංකල්ප තේරුම් ගන්න එක ඉතාම වැදගත්.

දැන් ඔයාලට පුළුවන් මේ දැනුම පාවිච්චි කරලා Public APIs (e.g., Weather APIs, GitHub API) එක්ක වැඩ කරන්න පුරුදු වෙන්න. නැත්නම් ඔයාලගේම සරල API එකක් හදන්න උත්සාහ කරන්න.

මේ ගැන ඔයාලට තියෙන අදහස්, ප්‍රශ්න පහළින් Comment කරන්න. මේ වගේ තවත් තාක්ෂණික ලිපි බලාපොරොත්තු වෙනවා නම්, අනිවාර්යයෙන්ම අපිට කියන්න! ආයෙත් මේ වගේ වටිනා ලිපියකින් හමුවෙමු!