REST API Basics: ඔබේ පළමු Spring Boot Controller එක - SC Guide

කොහොමද යාලුවනේ? අද අපි කතා කරන්න යන්නේ මේ දවස්වල Software Development ලෝකේ බොහොම ජනප්‍රිය දෙයක් ගැන – ඒ තමයි REST APIs. මොකද අද කාලේ අපි පාවිච්චි කරන Mobile App එකක ඉඳලා Web App එකක් දක්වා, හැම තැනකම Backend System එකක් එක්ක සන්නිවේදනය කරන්න මේ REST APIs පාවිච්චි කරනවා. ඒ කියන්නේ, Facebook, Instagram, Netflix, YouTube වගේ අපි හැමදාම පාවිච්චි කරන Apps පවා තමන්ගේ Server එක්ක කතා කරන්නේ මේ REST APIs හරහා තමයි.

"REST API" කියලා කියද්දි සමහරුන්ට නම් ටිකක් සංකීර්ණ වගේ පෙනුනත්, ඇත්තටම ඒක හරිම සරල concept එකක්. හරියට ඔයා Restaurant එකකට ගිහින් කෑම order කරනවා වගේ. ඔයාට කෑම හදන්න ඕනේ නැහැ, ඒකේ recipe එක දැනගන්න ඕනේ නැහැ. ඔයාට ඕනේ කෑමේ නම waiter ට කිව්වාම එයා ඒක ගෙනත් දෙනවා. REST API එකත් ඒ වගේ. Client (ඔයාගේ App එක) Server (Restaurant එක) එකෙන් දත්ත ඉල්ලනවා, Server එක ඒ දත්ත දෙනවා. ඒක නියමයි නේද?

මේ Article එකෙන් අපි බලමු REST API කියන්නේ මොකක්ද, ඒක කොච්චර වැදගත්ද, ඒ වගේම Backend Development වලට හරිම ජනප්‍රිය Framework එකක් වෙන Spring Boot පාවිච්චි කරලා කොහොමද සරල REST API එකක් හදාගන්නේ කියලා. ඔයා Backend Development අලුතින්ම පටන් ගන්න කෙනෙක් නම්, මේක ඔයාට හොඳ ආරම්භයක් වේවි. එහෙනම්, අපි පටන් ගමු!

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

REST කියන්නේ Representational State Transfer කියන එකට කෙටි යෙදුමක්. මේක 2000 අවුරුද්දේ Roy Fielding කියන කෙනා විසින් හඳුන්වා දුන්නු architectural style එකක්, ඒ කියන්නේ Web Services හදනකොට අපි අනුගමනය කරන්න ඕන Principles නැත්නම් නීති මාලාවක්. සරලවම කිව්වොත්, ඒක System දෙකකට (උදා: Mobile App එකක් සහ Server එකක්) එකිනෙකාට කතා කරන්න පුළුවන්, සම්මත ක්‍රමවේදයක්.

හිතන්න ඔයා Phone එකෙන් Facebook App එක open කරනවා කියලා. ඔයාගේ News Feed එක load වෙන්න, App එක Facebook Server එකට Request එකක් යවනවා. ඒ Request එක සහ Server එකේ Response එක සිදුවෙන්නේ REST Principles අනුව හදපු API එකක් හරහා. මෙතැනදී client (ඔයාගේ Facebook App) සහ server (Facebook Data Centers වල තියෙන server) අතර සන්නිවේදනය වෙන්නේ HTTP Protocol එක පාවිච්චි කරලා. ඒ කියන්නේ Web Sites Browse කරනකොට අපි පාවිච්චි කරන HTTP (Hypertext Transfer Protocol) එකම තමයි මේකටත් පාවිච්චි කරන්නේ.

RESTful Principles:

හොඳ RESTful API එකක් හදද්දි මේ මූලික Concepts හයක් තියෙනවා, ඒ ගැන ටිකක් ගැඹුරින් බලමු:

1. Client-Server Architecture:මේක තමයි පදනම. Client (උදා: Browser එකක්, Mobile App එකක්) සහ Server (ඔයාගේ Backend Service එක) කියන කොටස් දෙක පැහැදිලිවම වෙන් කරලා තියෙන්න ඕනේ. Client ට Server එක ගැන වැඩිය දැනගන්න ඕනේ නැහැ, ඒ වගේම Server එකට Client ගැන වැඩිය දැනගන්න ඕනේ නැහැ. ඒකෙන් වෙන්නේ දෙගොල්ලන්ටම තමන්ගේ වැඩේට focus කරන්න පුළුවන් වෙන එක. Server එකට දත්ත දෙන්න පුළුවන්, Client ට ඒ දත්ත display කරන්න පුළුවන්. මේකෙන් System එකේ Scalability (විශාල කරගැනීමේ හැකියාව) සහ Flexibility වැඩි වෙනවා.
2. Stateless:මේක හරිම වැදගත් Concept එකක්. REST API එකක් Stateless කියන්නේ, Server එකට පෙර Request එකක කිසිම තොරතුරක් මතක තියාගන්න බැහැ. හැම Request එකක්ම තමන්ට අවශ්‍ය හැම තොරතුරක්ම (Authentication details, data, etc.) අරගෙන එන්න ඕනේ. හරියට ඔයා බැංකුවකට ගිහින් හැම පාරම මුල ඉඳන්ම ඔයා කවුද කියලා කියනවා වගේ. මේකෙන් Server එකේ Complexity එක අඩු වෙනවා, මොකද Server එකට Sessions manage කරන්න අවශ්‍ය වෙන්නේ නැහැ. ඕනෑම Request එකක් ඕනෑම Server එකකට Handle කරන්න පුළුවන් නිසා System එකේ Reliability එකත් වැඩි වෙනවා.
3. Cacheable:Client ට Server එකෙන් ලැබෙන Responses Cache කරන්න පුළුවන් වෙන්න ඕනේ. ඒ කියන්නේ, සමහර දත්ත නැවත නැවත ඉල්ලන්න අවශ්‍ය නැහැ. Server එකෙන් දත්ත ලැබෙනකොට ඒක කොච්චර වෙලාට Cache කරලා තියාගන්න පුළුවන්ද කියලා Server එකම Client ට කියන්න පුළුවන්. මේකෙන් Network Traffic එක අඩු වෙනවා වගේම, System එකේ Performance එකත් වැඩි වෙනවා. උදාහරණයක් විදිහට, ඔයාගේ profile picture එක හැමදාම වෙනස් වෙන්නේ නැති නිසා, ඒක Cache කරලා තියාගන්න පුළුවන්.
4. Uniform Interface:මේක තමයි REST වල වැදගත්ම දේ. මේකෙන් වෙන්නේ client සහ server අතර සන්නිවේදනයට සම්මත ක්‍රමවේදයක් (standard way) සකස් වෙන එක. මේකට මූලිකම දේවල් හතරක් තියෙනවා:
   • Identification of Resources: හැම දත්ත කොටසක්ම (User කෙනෙක්, Product එකක්) 'Resource' එකක් විදිහට දකිනවා. ඒ වගේම හැම Resource එකකටම අද්විතීය URI (Uniform Resource Identifier) එකක් තියෙනවා. (උදා: /users/123, /products/abc)
   • Manipulation of Resources through Representations: Client ට Resource එකක් වෙනස් කරන්න පුළුවන් වෙන්නේ ඒ Resource එකේ Representation (උදා: JSON, XML) එකක් යවලා.
   • Self-Descriptive Messages: හැම Message එකකම (Request/Response) ඒ Message එක තේරුම් ගන්න අවශ්‍ය හැම තොරතුරක්ම තියෙන්න ඕනේ. (උදා: HTTP headers like Content-Type)
   • Hypermedia as the Engine of Application State (HATEOAS): මේක ටිකක් advanced Concept එකක්. ඒකෙන් කියන්නේ, Response එකක ඉදිරි Action වලට අවශ්‍ය Links අඩංගු වෙන්න ඕනේ කියලා. (උදා: User details request කරනකොට, ඒ user ගේ posts වලට link එකක් දෙනවා වගේ). මේකෙන් Client ට API එක Explore කරන්න පුළුවන්.
5. Layered System:Client ට කෙලින්ම Server එකට කතා කරන්න පුළුවන් වගේම, Client ට නොදැනීම අතරමැදි Layers (Load Balancers, Proxy Servers, Caching Servers) තියෙන්නත් පුළුවන්. මේ Layered Architecture එක System එකේ Security එක, Scalability එක සහ Performance එක වැඩි කරන්න උදව් වෙනවා.
6. Code on Demand (Optional):මේක Optional Principle එකක්. Server එකට Client එකට executable code (උදා: JavaScript) යවන්න පුළුවන්. මේක Web Applications වලට සාමාන්‍යයි. මේකෙන් Client එකේ Functionality එක dynamic කරන්න පුළුවන්.

REST වල Core Ideas (Core Ideas of REST)

REST API එකක් ගැන කතා කරනකොට, අපි සාමාන්‍යයෙන් කතා කරන මූලික අදහස් දෙකක් තියෙනවා:

1. Resources:REST API එකකදි අපි හැමදේම දකින්නේ "Resources" විදිහට. මේ Resources කියන්නේ අපේ System එකේ තියෙන ඕනෑම Entity එකක් වෙන්න පුළුවන්. උදාහරණයක් විදිහට, User කෙනෙක්, Product එකක්, Order එකක්, Post එකක් – මේ හැම එකක්ම Resource එකක්. මේ Resources වලට අද්විතීය URI (Uniform Resource Identifier) එකක් තියෙනවා. මේ URI එකෙන් තමයි අපි ඒ Resource එක identify කරන්නේ. හරියට ඔයාගේ ගෙදරට Address එකක් තියෙනවා වගේ. උදාහරණ: /users (සියලුම users), /users/123 (ID 123 තියෙන user), /products/laptop (laptop කියන product එක).
2. HTTP Methods:අපි මේ Resources එක්ක වැඩ කරන්න HTTP Methods පාවිච්චි කරනවා. මේවා තමයි අපේ Request එකේ "ක්‍රියාව" මොකක්ද කියලා Server එකට කියන්නේ. මේවා සාමාන්‍යයෙන් CRUD (Create, Read, Update, Delete) Operations වලට Map වෙනවා.
   • GET:Resource එකක දත්ත ලබාගන්න (Read). අපි Web Browser එකක URL එකක් type කරලා Enter කරනකොට වෙන්නේ GET Request එකක් යන එක. උදා: GET /users/123 (ID 123 තියෙන user ගේ විස්තර ගන්න).
   • POST:අලුත් Resource එකක් හදන්න (Create). උදා: POST /users (අලුත් user කෙනෙක් add කරන්න).
   • PUT:දැනට තියෙන Resource එකක් update කරන්න (Update). සාමාන්‍යයෙන් මේකෙන් Resource එකේ හැම Field එකක්ම update කරනවා. උදා: PUT /users/123 (ID 123 තියෙන user ගේ විස්තර update කරන්න).
   • DELETE:Resource එකක් delete කරන්න (Delete). උදා: DELETE /users/123 (ID 123 තියෙන user ව delete කරන්න).
   • PATCH:මේකත් Update කරන්න පාවිච්චි කරනවා. හැබැයි PUT වගේ හැම Field එකක්ම update නොකර, තෝරාගත් Field කිහිපයක් update කරන්න (Partial Update). (මේකත් දැනගෙන ඉන්න එක හොඳයි)

Spring Boot එක්ක REST API හදමු (Let's Build a REST API with Spring Boot)

දැන් අපි බලමු මේ REST Principles කොහොමද Spring Boot project එකකදී implement කරන්නේ කියලා. Spring Boot කියන්නේ Spring Framework එකේම කොටසක්. ඒකෙන් Backend Applications හදන එක හරිම ලේසි කරනවා. බොහොමයක් Configurations අපිට අතින් කරන්න ඕනේ නැහැ. ඒක තමයි Spring Boot වල ලොකුම වාසිය.

පූර්ව අවශ්‍යතා (Prerequisites):

• Java Development Kit (JDK) 11 හෝ ඊට ඉහළ: ඔයාගේ Computer එකේ Java Install කරලා තියෙන්න ඕනේ.
• Maven හෝ Gradle: Project එකේ Dependencies Manage කරන්න. Spring Boot Project එකක් හදනකොට මේක automatically setup වෙනවා.
• IDE එකක්: IntelliJ IDEA Community Edition, VS Code, Eclipse වගේ එකක් පාවිච්චි කරන්න පුළුවන්.

Project එක හදමු (Create the Project):

Spring Boot Project එකක් හදන්න ලේසිම ක්‍රමය තමයි Spring Initializr කියන Web Tool එක පාවිච්චි කරන එක. මේක Spring Boot Development වලට අත්පොත් තියන ඕනෑම කෙනෙක්ට හොඳම තැනක්.

1. ඔබේ Web Browser එක Open කරලා https://start.spring.io/ කියන Address එකට යන්න.
2. එතනදී පහත විදිහට Details Select කරන්න:
   • Project: Maven Project (නැත්නම් Gradle Project, කැමති එකක්)
   • Language: Java
   • Spring Boot: (latest stable version - මේක Article එක ලියන වෙලාවට 3.x.x වගේ එකක් වෙන්න පුළුවන්)
   • Group: com.example වගේ දෙයක් දෙන්න. (ඔයාගේ Company Domain එකේ Reverse එක)
   • Artifact: restapibasics වගේ නමක් දෙන්න. (ඔයාගේ Project එකේ නම)
   • Name: restapibasics
   • Description: Demo project for Spring Boot REST API basics
   • Package name: com.example.restapibasics (මේක 자동으로 generate වෙයි)
   • Packaging: Jar (War කියන්නෙ Web Applications වලට, අපිට දැන් Jar ඇති)
   • Java: 17 (නැත්නම් ඔබ install කරලා තියෙන JDK version එකට ගැලපෙන එකක්)
3. දැන් "Dependencies" කොටසට යන්න. මෙතනදී අපි අපේ Project එකට අවශ්‍ය Libraries මොනවද කියලා කියනවා.
   • "Add Dependencies..." button එක Click කරලා "Spring Web" කියලා Search කරලා ඒක Add කරන්න. මේක තමයි Web Applications, ඒ කියන්නේ REST APIs වගේ ඒවා හදන්න අපිට අවශ්‍ය Core Library එක.
4. අවසානයේදී "Generate" button එක Click කරන්න. එතකොට restapibasics.zip වගේ Zip File එකක් Download වෙයි.
5. ඒ Zip File එක Extract කරලා, ඔයාගේ කැමති IDE එකෙන් (IntelliJ IDEA, VS Code වගේ) ඒ Project එක Open කරන්න. IDE එක විසින් අවශ්‍ය Dependencies Download කරලා Project එක Build කරයි.

@RestController හා @GetMapping (Understanding @RestController and @GetMapping):

Spring Boot වලදී REST API හදනකොට අපිට @RestController කියන Annotation එක ගොඩක් වැදගත්. Annotation කියන්නේ Java වලදී Code එකට Metadata add කරන්න පාවිච්චි කරන දෙයක්. Spring Framework එක මේ Metadata කියවලා ඒ අනුව වැඩ කරනවා.

• @RestController:මේක ඇත්තටම @Controller සහ @ResponseBody කියන Annotation දෙකේ එකතුවක්.ඉතින් @RestController පාවිච්චි කරාම, අපිට වෙනම @ResponseBody දාන්න අවශ්‍ය නැහැ. ඒක ගොඩක් පහසුයි.
  • @Controller: මේක Spring Framework එකට කියනවා මේ Class එක "Controller" එකක් කියලා. Controller එකක වැඩේ තමයි Incoming HTTP Requests Handle කරන එක.
  • @ResponseBody: මේක කියන්නේ මේ Controller එකේ Methods වලින් Return කරන Java Object එකක් HTTP Response Body එක විදිහට Client ට යවන්න ඕනේ කියලා. සාමාන්‍යයෙන් මේවා JSON (JavaScript Object Notation) නැත්නම් XML (eXtensible Markup Language) format වලට Convert වෙලා තමයි යන්නේ.
• @GetMapping:මේ Annotation එක පාවිච්චි කරන්නේ HTTP GET requests Handle කරන්න. මේක Method එකක් උඩින් දානවා. ඒකට Path එකක් දෙනවා, ඒ Path එකට එන GET Request එකක් ආවම මේ Method එක Execute වෙනවා.

සරලම REST Endpoint එක (Our Simplest REST Endpoint):

දැන් අපි අපේ Project එකට ගිහින් සරලම REST Endpoint එකක් හදමු. IDE එකේ Project Structure එකේ src/main/java/com/example/restapibasics (ඔබගේ Package නමට අනුව වෙනස් වෙන්න පුළුවන්) යටතේ අලුත් Java Class එකක් හදන්න. ඒකට HelloWorldController.java වගේ නමක් දෙන්න.

package com.example.restapibasics; // ඔබගේ package නමට අනුව වෙනස් කරන්න

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloWorldController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, Spring Boot!";
    }
}

Code Explanation:

• package com.example.restapibasics;: මේක ඔබගේ Project එකේ Package එකේ නම. ඔබ Project එක හදද්දි දුන්නු Group සහ Artifact name එක අනුව මේක වෙනස් වෙන්න පුළුවන්.
• import org.springframework.web.bind.annotation.GetMapping; සහ import org.springframework.web.bind.annotation.RestController;: අපි පාවිච්චි කරන @GetMapping සහ @RestController Annotation වලට අවශ්‍ය Class Path මෙතනින් Import කරගන්නවා.
• @RestController: අපි මේ Class එකට මේ Annotation එක දානවා. මේකෙන් Spring Boot Framework එකට කියනවා මේ Class එක REST API Endpoint එකක් Handle කරන Controller එකක් කියලා.
• public class HelloWorldController { ... }: මේක තමයි අපේ Controller Class එක.
• @GetMapping("/hello"): මේකෙන් කියන්නේ මේ sayHello() Method එක Execute වෙන්නේ /hello කියන URL Path එකට HTTP GET Request එකක් ආවොත් විතරයි කියලා. ඒ කියන්නේ, http://localhost:8080/hello වගේ URL එකකට Request එකක් ආවොත් මේ Method එක ක්‍රියාත්මක වෙනවා.
• public String sayHello() { ... }: මේක තමයි අපේ Method එක. මේකෙන් String එකක් Return කරනවා.
• return "Hello, Spring Boot!";: මේ Method එකෙන් Return කරන String එක, HTTP Response Body එක විදිහට Client ට යනවා.

Run කරලා බලමු (Let's Run and Test):

දැන් අපි හදාගත්ත API එක වැඩ කරනවද කියලා බලමු. මේක හරිම ලේසියි.

1. ඔබේ IDE එකෙන් Main Application Class එක Run කරන්න. මේකට සාමාන්‍යයෙන් YourProjectApplication.java (අපේ නම් RestapibasicsApplication.java) වගේ නමක් තියෙනවා. ඒකේ main Method එකක් තියෙනවා.
   • IntelliJ IDEA වල නම්, ඒ Class එක Open කරලා, Green Play button එක Click කරන්න.
   • VS Code වල නම්, Run and Debug tab එකට ගිහින් Run කරන්න.
2. Console එකේ "Started YourProjectApplication in..." වගේ Message එකක් පෙනෙයි. Spring Boot Application එක Default Port එක 8080 එකේ Run වෙනවා.
3. දැන් Web Browser එකක් Open කරලා http://localhost:8080/hello කියලා type කරලා Enter කරන්න.
4. එතකොට ඔබට "Hello, Spring Boot!" කියලා Message එක Browser එකේ පෙනෙයි. ඒක තමයි ඔබ සාර්ථකව හදාගත්ත පළමු REST API Endpoint එක! නියමයි නේද?

ඔබට Postman, Insomnia, නැත්නම් curl command line tool වගේ REST Client Tools පාවිච්චි කරන්නත් පුළුවන් මේ API එක Test කරන්න. උදාහරණයක් විදිහට, Command Prompt/Terminal එකේ:

curl http://localhost:8080/hello

මේක Run කරාම Output එක "Hello, Spring Boot!" කියලා ලැබෙයි.

තව දුරටත් ඉගෙන ගමු (Learning More)

මේක ආරම්භයක් විතරයි. REST APIs වලට තව ගොඩක් දේවල් තියෙනවා. මේවා ගැන ඉස්සරහට ඉගෙන ගන්න එකෙන් ඔබට හොඳ Backend Developer කෙනෙක් වෙන්න පුළුවන්:

• Path Variables:URL එකේ කොටසක් විදිහට දත්ත යවන හැටි. උදා: /users/{id} වගේ Path එකක්. මෙතනදී {id} කියන්නේ dynamic value එකක්.
• Request Parameters:URL එකේ Query Parameters විදිහට දත්ත යවන හැටි. උදා: /products?category=electronics&minPrice=1000 වගේ.
• Request Body:POST/PUT Request වලට JSON/XML format වලින් දත්ත යවන හැටි.
• HTTP Status Codes:API එකෙන් Request එකේ තත්වය ගැන කියන්න පාවිච්චි කරන Standard Codes. උදා: 200 OK (සාර්ථකයි), 404 Not Found (Resource එකක් නැහැ), 500 Internal Server Error (Server එකේ වැරැද්දක්).
• Error Handling:API එකේ වැරදි සිදුවුනොත් ඒවා handle කරන හැටි.
• Security:API එක ආරක්ෂා කරන හැටි (Authentication, Authorization).
• DTOs (Data Transfer Objects):Client සහ Server අතර දත්ත හුවමාරු කරගන්න පාවිච්චි කරන Java Objects.

මේ හැම දෙයක්ම ඔයාට ඉස්සරහට ඉගෙන ගන්න පුළුවන්. Spring Boot documentation එක සහ Online Tutorials ගොඩක් මේවා ගැන තොරතුරු දෙනවා.

Conclusion

ඉතින් යාලුවනේ, අද අපි REST API කියන්නේ මොකක්ද, ඒකේ මූලික Principles මොනවද, ඒ වගේම Spring Boot framework එක පාවිච්චි කරලා සරලම REST API endpoint එකක් කොහොමද හදාගන්නේ කියලා ඉගෙන ගත්තා. මේක ඔයාගේ Software Development ගමනේ ඉතා වැදගත් පියවරක්. මොකද අද කාලේ තියෙන Microservices Architecture වලදී මේ REST APIs වලට තියෙන ඉල්ලුම බොහොම වැඩියි. ලොකු System එකක් වෙනුවට පොඩි පොඩි Services ගොඩක් හදලා ඒ Services එකිනෙකා එක්ක කතා කරන්නේ මේ REST APIs හරහා තමයි.

දැන් ඔයාට පුළුවන් මේක Try කරලා බලන්න. ඔයාගේම Project එකක් හදලා මේ Article එකේ තියෙන විදිහට Endpoint එකක් හදලා Run කරලා බලන්න. මොනවා හරි ප්‍රශ්න තියෙනවා නම්, Comment section එකේ අහන්න. අපි පුළුවන් හැම වෙලාවෙම උදව් කරන්න ලෑස්තියි.

තව මොනවා ගැනද ඔයාලා දැනගන්න කැමති? අනිවාර්යෙන්ම අපිව දැනුවත් කරන්න. එහෙනම්, තවත් Article එකකින් හමුවෙමු! Happy Coding!