Java RESTful Web Services Tutorial | JAX-RS Sinhala Guide | REST Principles in Java

ආයුබෝවන් යාළුවනේ! අද අපි කතා කරමු Software Engineering වල ගොඩක් වැදගත් මාතෘකාවක් ගැන – RESTful Web Services.

දැන් කාලේ හැම Application එකක්ම වගේ වෙනත් Application එක්ක communicate කරනවා, data share කරනවා. Social media apps, online shopping sites, banking apps වගේ මොනවා ගත්තත් මේ හැම එකක්ම Backend server එක්ක කතා කරන්නේ, එහෙම නැත්නම් වෙනත් services එක්ක සම්බන්ධ වෙන්නේ Web Services හරහා. ඒ වගේ Communication Method වලින්, RESTful Web Services කියන්නේ ගොඩක් ජනප්‍රිය, සරල, සහ බලවත් විදියක්.

ඔයා Software Engineering field එකේ ඉන්න කෙනෙක් නම්, නැත්නම් ඒ පැත්තට එන්න බලාපොරොත්තු වෙන කෙනෙක් නම්, REST ගැන හරියටම දැනගන්න එක අත්‍යාවශ්‍ය දෙයක්. ඒ වගේම Java developersලට RESTful services හදන්න තියෙන standard API එක තමයි JAX-RS (Java API for RESTful Web Services) කියන්නේ. මේ article එකෙන් අපි RESTful services කියන්නේ මොනවද, ඒවායේ මූලික සිද්ධාන්ත (principles) මොනවද, සහ Java වල JAX-RS පාවිච්චි කරලා කොහොමද සරල RESTful service එකක් හදන්නේ කියලා පියවරෙන් පියවර බලමු. එහෙනම් අපි පටන් ගමු!

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

REST (Representational State Transfer) කියන්නේ architectural style එකක්, එහෙම නැත්නම් Web services හදනකොට අනුගමනය කරන්න ඕන නීති මාලාවක්. මේක HTTP protocol එකේ තියෙන හැකියාවන් උපරිමයෙන් ප්‍රයෝජනයට ගන්නවා. RESTful system එකක් හදනකොට අපි අනුගමනය කරන්න ඕන ප්‍රධාන සිද්ධාන්ත කිහිපයක් තියෙනවා. මේවා තමයි:

1. Client-Server Architecture: මේකෙදි Client (mobile app, web browser) සහ Server එක (ඔයාගේ service එක run වෙන තැන) කියන දෙක එකිනෙකින් වෙන් වෙලා වැඩ කරනවා. ඒ කියන්නේ Client එකට Server එකේ business logic එක ගැන හිතන්න ඕන නෑ. Server එකටත් Client එකේ User Interface (UI) එක ගැන හිතන්න ඕන නෑ. මේ වෙන්වීම නිසා දෙකම වෙන වෙනම develop කරන්න, update කරන්න සහ scale කරන්න ලේසියි.
2. Statelessness: මේක තමයි REST වල තියෙන ගොඩක් වැදගත් ලක්ෂණයක්. ඒ කියන්නේ Server එකට Client එකේ කලින් request එක ගැන මතකයක් නෑ. හැම request එකක්ම තනියෙන් ක්‍රියාත්මක වෙන්න පුළුවන් වෙන්න ඕන. හැම request එකකම Server එකට අවශ්‍ය කරන හැම තොරතුරක්ම (authentication info, session info වගේ) අඩංගු වෙලා තියෙන්න ඕන. මේ නිසා Server එකට එකවර ගොඩක් requests handle කරන්න පුළුවන් වෙනවා, මොකද Server එකට Client ගේ state එක maintain කරන්න අවශ්‍ය වෙන්නේ නැති නිසා.
3. Cacheability: Web එකේ performance එක වැඩි කරන්න Cache එකක් කියන්නේ අත්‍යාවශ්‍ය දෙයක්. RESTful service එකකින් එවන Response එක Cache කරන්න පුළුවන්ද බැරිද කියලා Server එකට කියන්න පුළුවන්. ඒ නිසා Client එකට කලින් ගත්තු data නැවත නැවත Server එකෙන් ඉල්ලන්නේ නැතිව, Cache එකෙන් ගන්න පුළුවන්.
4. Uniform Interface: මේක තමයි REST වල තියෙන තවත් ප්‍රධාන ලක්ෂණයක්. මේකෙදි resources (data) access කරන විදිය standard කරනවා. මේක ප්‍රධාන දේවල් හතරකින් සමන්විත වෙනවා:
   • Identification of Resources: හැම resource එකකටම (උදා: user, product, order) unique identifier එකක් තියෙන්න ඕන (URI - Uniform Resource Identifier). උදාහරණයක් විදියට, /users/123 කියන්නේ 123 කියන ID එක තියෙන user ගේ resource එක.
   • Manipulation of Resources Through Representations: Client එකක් resource එකක් modify කරන්න ඕන නම්, ඒ resource එකේ representation එකක් (e.g., JSON, XML) Server එකට යවනවා. Server එක ඒ representation එක පාවිච්චි කරලා resource එක update කරනවා.
   • Self-descriptive Messages: Server එකෙන් එන හැම response එකකම තමන් ගැනම විස්තරයක් තියෙන්න ඕන. ඒ කියන්නේ ඒ response එකට මොන MediaType එකක්ද තියෙන්නේ (JSON ද, XML ද), මොන status code එකද තියෙන්නේ (200 OK, 404 Not Found), සහ ඊට අදාළව මොනවා කරන්න පුළුවන්ද (e.g., links to related resources) වගේ දේවල්.
   • HATEOAS (Hypermedia As The Engine Of Application State): මේක ටිකක් advanced concept එකක්. මේකෙදි Server එක Client එකට කියනවා ඊළඟට කරන්න පුළුවන් දේවල් මොනවද කියලා links හරහා. උදාහරණයක් විදියට, user ගේ details එක්කම, ඒ user ගේ orders බලන්න පුළුවන් link එකක් දෙනවා. මේක නිසා Client එකට Server එකේ තියෙන options ගැන කලින් දැනගන්න ඕන වෙන්නේ නෑ.
5. Layered System: RESTful system එකක Client එකට Server එකේ ස්ථර කීයක් (layers) තියෙනවද කියලා දැනගන්න අවශ්‍ය නෑ. ඒ කියන්නේ Server එක Proxy servers, load balancers, security layers වගේ තවත් layers පිටිපස්සේ තියෙන්න පුළුවන්. මේ නිසා system එකේ scalability සහ security වැඩි වෙනවා.

මේ principles ටික හරියට තේරුම් ගත්තොත් ඔයාට හොඳ RESTful APIs design කරන්න ලේසි වෙයි.

JAX-RS: Java වල RESTful Web Services හදන්න අත්පොත (JAX-RS: The Handbook for Building RESTful Web Services in Java)

JAX-RS කියන්නේ Java වල RESTful web services හදන්න තියෙන standard API එක. මේක Java EE (Enterprise Edition) වල කොටසක්. JAX-RS වල තියෙන විශේෂත්වය තමයි මේක annotations පාවිච්චි කරලා services හදන එක ගොඩක් පහසු කරනවා. JAX-RS වල ජනප්‍රිය implementations දෙකක් තමයි Jersey (Reference Implementation) සහ RESTEasy කියන්නේ.

අපි දැන් බලමු JAX-RS වල තියෙන ප්‍රධාන annotations මොනවද කියලා.

ප්‍රධාන Annotations (Key Annotations):

• @Path: මේ annotation එක පාවිච්චි කරන්නේ HTTP request එකක් map කරන්න ඕන resource එකේ path එක specify කරන්න. Class එකකට උඩින් දානකොට base path එක දෙනවා, method එකකට උඩින් දානකොට sub-path එකක් දෙනවා.
• HTTP Method Annotations:
  • @GET: Resource එකකින් data ගන්න (read) පාවිච්චි කරනවා.
  • @POST: අලුත් resource එකක් හදන්න (create) පාවිච්චි කරනවා.
  • @PUT: දැනට තියෙන resource එකක් update කරන්න (update) පාවිච්චි කරනවා, නැත්නම් අලුත් එකක් හදන්න (upsert) පාවිච්චි කරනවා.
  • @DELETE: Resource එකක් delete කරන්න (delete) පාවිච්චි කරනවා.
• @Produces: Server එක Client එකට එවන response එකේ media type (content type) එක මොකක්ද කියලා මේකෙන් specify කරනවා. උදා: MediaType.APPLICATION_JSON, MediaType.TEXT_PLAIN.
• @Consumes: Client එක Server එකට එවන request body එකේ media type එක මොකක්ද කියලා මේකෙන් specify කරනවා. උදා: MediaType.APPLICATION_JSON.
• @PathParam: URL Path එකේ කොටසක් method එකේ parameter එකකට map කරන්න පාවිච්චි කරනවා. උදා: /users/{id} එකේ {id} ගන්න.
• @QueryParam: URL එකේ query string එකෙන් (?name=value) parameter එකක් ගන්න පාවිච්චි කරනවා. උදා: /products?category=electronics එකේ category ගන්න.
• @FormParam: HTML form submit එකකින් එන form data ගන්න පාවිච්චි කරනවා.
• @HeaderParam: HTTP request එකේ Header එකකින් අගයක් ගන්න පාවිච්චි කරනවා.

සරල JAX-RS Resource එකක් හදමු! (Let's Build a Simple JAX-RS Resource!)

දැන් අපි බලමු කොහොමද JAX-RS පාවිච්චි කරලා සරල RESTful service එකක් හදන්නේ කියලා. මේක අපි Jersey (JAX-RS implementation එකක්) පාවිච්චි කරලා හදමු.

පළමුවෙන්ම, ඔයාගේ pom.xml (Maven project එකක් නම්) file එකට අවශ්‍ය dependency එක එකතු කරගන්න ඕන. Jersey server dependency එක මෙහෙම එකතු කරන්න පුpලුවන්:

<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-servlet</artifactId>
    <version>3.0.4</version> <!-- හෝ නවතම stable version එකක් -->
</dependency>
<dependency>
    <groupId>org.glassfish.jersey.inject</groupId>
    <artifactId>jersey-hk2</artifactId>
    <version>3.0.4</version> <!-- හෝ නවතම stable version එකක් -->
</dependency>

ඊට පස්සේ, අපි අපේ පළවෙනි RESTful resource එක හදමු. මේක HelloResource.java කියලා file එකක් විදියට හදමු.

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.PathParam;

@Path("/hello") // Base path for this resource
public class HelloResource {

    // Method to handle GET requests to /hello
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String getHelloMessage() {
        return "ආයුබෝවන් RESTful ලෝකයට!"; // "Welcome to the RESTful world!"
    }

    // Method to handle GET requests to /hello/name/{yourName}
    @GET
    @Path("/name/{name}")
    @Produces(MediaType.TEXT_PLAIN)
    public String getHelloName(@PathParam("name") String name) {
        return "ආයුබෝවන් " + name + ", REST service එක සාර්ථකයි!"; // "Hello " + name + ", REST service is successful!"
    }

    // Method to demonstrate JSON response
    @GET
    @Path("/json")
    @Produces(MediaType.APPLICATION_JSON)
    public String getHelloJson() {
        return "{\"message\": \"ආයුබෝවන් JSON ලෝකයට!\"}"; // "Welcome to the JSON world!" - for simplicity, returning a String
    }
}

මේ Code එක ගැන පැහැදිලි කරමු:

• @Path("/hello"): මේකෙන් කියවෙන්නේ මේ HelloResource class එක /hello කියන URL path එකට map වෙනවා කියලයි. ඒ කියන්නේ මේ class එකේ තියෙන methods වලට access කරන්න /hello කියන path එක use කරන්න වෙනවා.
• @GET: මේ annotation එකෙන් කියවෙන්නේ getHelloMessage() method එක HTTP GET requests handle කරනවා කියලයි.
• @Produces(MediaType.TEXT_PLAIN): මේකෙන් කියවෙන්නේ මේ method එකෙන් return කරන data එක plain text විදියට client එකට යනවා කියලයි. MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML වගේ වෙනත් media types ද තියෙනවා.
• @Path("/name/{name}"): මේක /hello යටතේ තියෙන sub-path එකක්. {name} කියන්නේ Path parameter එකක්.
• @PathParam("name") String name: මේකෙන් කියවෙන්නේ URL එකේ {name} කියන තැනට එන අගය name කියන String variable එකට assign වෙනවා කියලයි.
• @Produces(MediaType.APPLICATION_JSON): තුන්වෙනි method එකෙන් JSON response එකක් return කරන හැටි පෙන්නනවා. සරලව String එකක් JSON format එකට හැරෙව්වා. Real world app එකක නම් ඔයාට JSON objects convert කරන්න Jackson වගේ Library එකක් පාවිච්චි කරන්න පුළුවන්.

Service එක run කරන්නේ කොහොමද?

මේ service එක deploy කරන්න ඔයාට Servlet Container එකක් (Apache Tomcat, Jetty වගේ) නැත්නම් Application Server එකක් (GlassFish, WildFly වගේ) අවශ්‍ය වෙනවා. නැත්නම් Grizzly වගේ embedded server එකක් පාවිච්චි කරන්නත් පුළුවන්. සරලම විදියට Tomcat එකක deploy කරනවා නම්, web.xml file එකේ Jersey Servlet එක configure කරන්න ඕන.

උදාහරණයක් විදියට, src/main/webapp/WEB-INF/web.xml file එක මෙහෙම වෙන්න පුළුවන්:

<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

    <servlet>
        <servlet-name>jersey-servlet</servlet-name&naturally      <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
        <init-param>
            <param-name>jersey.config.server.provider.packages</param-name>
            <param-value>com.example.rest</param-value> <!-- Change to your package name -->
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>jersey-servlet</servlet-name>
        <url-pattern>/api/*</url-pattern> <!-- Base URL for your API -->
    </servlet-mapping>

</web-app>

මතක තියාගන්න com.example.rest කියන තැනට ඔයාගේ project එකේ resource files තියෙන package name එක දෙන්න ඕන. /api/* කියන url-pattern එකෙන් කියවෙන්නේ /api/ යටතේ එන හැම request එකක්ම Jersey Servlet එකට යනවා කියලයි. ඉතින් අපේ HelloResource එක /api/hello වගේ URL එකකින් access කරන්න පුළුවන් වෙයි.

Tomcat වගේ server එකක project එක deploy කරලා start කරාට පස්සේ, ඔයාට මේ URL වලින් test කරන්න පුළුවන්:

• http://localhost:8080/your-app-context/api/hello
• http://localhost:8080/your-app-context/api/hello/name/Kamal
• http://localhost:8080/your-app-context/api/hello/json

your-app-context කියන්නේ ඔයාගේ web application එක deploy කරනකොට දෙන නම. (හොඳටමම පැහැදිලිව තේරුම් ගන්න නම්, netbeans, IntelliJ IDEA හෝ eclipse වගේ IDE එකක web project එකක් හදලා මේක try කරලා බලන්න. එතකොට build and run කරන්න පහසුයි.)

නිගමනය (Conclusion)

ඉතින් යාලුවනේ, මේ article එකෙන් අපි RESTful Web Services වල මූලික සිද්ධාන්ත මොනවද, සහ Java වල JAX-RS framework එක පාවිච්චි කරලා කොහොමද සරල RESTful service එකක් හදන්නේ කියලා ඉගෙන ගත්තා. REST කියන්නේ Web development වල අත්‍යාවශ්‍ය කොටසක්. ඒ වගේම JAX-RS කියන්නේ Java developersලට RESTful APIs හදන එක ගොඩක් පහසු කරන powerful tool එකක්.

මේ දැනුම ඔයාට ඔයාගේ ඊළඟ project එකේදී RESTful services හදන්න අත්තිවාරමක් වෙයි කියලා හිතනවා. මතක තියාගන්න, හොඳ API එකක් හදන එක කියන්නේ design principles ගැන හොඳ අවබෝධයක් එක්ක practical experience එකත් අවශ්‍ය වෙන දෙයක්. ඉතින් මේක තවත් practice කරන්න, විවිධ scenarios වලට ගැලපෙන විදියට services හදලා බලන්න.

ඔයාට මේ ගැන මොනවා හරි ප්‍රශ්න තියෙනවා නම්, නැත්නම් ඔයාගේ අත්දැකීම් ගැන කියන්න ඕන නම්, පහලින් comment කරන්න. හැමදාම අලුත් දේවල් ඉගෙන ගන්න උනන්දු වෙන්න! ජය වේවා!