REST API වල HTTP Methods | User CRUD API සිංහලෙන් | SC Guide

ආයුබෝවන් කට්ටිය! කොහොමද ඉතින්? අද අපි කතා කරමු software development වලදී අත්‍යවශ්‍යම topic එකක් ගැන. ඒ තමයි REST API වල HTTP Methods. විශේෂයෙන්ම, GET, POST, PUT, DELETE කියන methods හතර ගැන විස්තරාත්මකව කතා කරලා, ඒ ටික පාවිච්චි කරලා කොහොමද සරල 'User' කෙනෙක්ගේ CRUD (Create, Read, Update, Delete) API එකක් හදාගන්නේ කියලා බලමු. මේක ඔයාලට API development ගැන හොඳ අවබෝධයක් ගන්න උදව් වෙයි කියලා හිතනවා. එහෙනම්, වැඩේට බහිමු!

අපි දන්නවා Web එක කියන්නේ clients (උදා: web browser එකක්, mobile app එකක්) සහ servers අතර සිදුවන communication එකක්. මේ communication එක සිදුවෙන්නේ HTTP (Hypertext Transfer Protocol) කියන protocol එක හරහා. REST API කියන්නේ මේ HTTP protocol එක මත හදලා තියෙන architectural style එකක්. මේකෙන් වෙන්නේ client එකට server එකේ තියෙන resources (දත්ත) request කරන්න, update කරන්න, අලුතින් හදන්න, නැත්නම් delete කරන්න පුළුවන් වෙන එක. මේ හැම ක්‍රියාවකටම නිශ්චිත HTTP Method එකක් තියෙනවා.

HTTP Methods කියන්නේ මොනවාද?

සරලව කිව්වොත්, HTTP Method එකක් කියන්නේ client එක server එකට යවන request එක මොන වගේ එකක්ද කියලා server එකට කියන විදිය. ඔයා කඩයකට ගිහින් 'මට බත් පැකට් එකක් දෙන්න' කියලා කියනවා වගේ දෙයක් තමයි. මෙතන 'බත් පැකට් එකක් දෙන්න' කියන එක තමයි method එක. server එකට තේරෙනවා 'අනේ, මේ client එක මගෙන් data ටිකක් ගන්න හදන්නේ' කියලා. HTTP methods වලට verbs (ක්‍රියා පද) කියලත් කියනවා, මොකද ඒවා client එකට server එක මත කරන්න පුළුවන් ක්‍රියා (actions) පෙන්නනවා.

RESTful API එකකදී, මේ methods යොදාගන්නේ server එකේ තියෙන specific resources (සම්පත්) මත ක්‍රියා කරන්න. උදාහරණයක් විදියට, 'users' කියන resource එකක් තියෙනවා නම්, අපි ඒකේ ඉන්න user ලා බලන්න, අලුත් user කෙනෙක් add කරන්න, user කෙනෙක්ගේ විස්තර update කරන්න, නැත්නම් user කෙනෙක් delete කරන්න මේ methods භාවිතා කරනවා.

HTTP Methods වලදී වැදගත් concept දෙකක් තියෙනවා: Idempotency සහ Safety.

• Safety: මේකෙන් කියන්නේ method එකක් server එකේ state එක වෙනස් කරන්නේ නැත්නම් ඒක safe කියන එක. (උදා: GET request එකකින් data retrieve කරනවා මිසක් database එකට වෙනසක් කරන්නේ නැහැ)
• Idempotency: මේකෙන් කියන්නේ method එකක් කීප සැරයක් run කලත් server එකේ state එක එකම විදියට පවතිනවා නම් ඒක Idempotent කියන එක. (උදා: DELETE request එකක් කීප සැරයක් යැව්වත් resource එක එක සැරයක් විතරයි delete වෙන්නේ.)

HTTP Methods ටිකක් විස්තරාත්මකව බලමු

GET Method

GET method එක පාවිච්චි කරන්නේ server එකෙන් data retrieve කරන්න. ඒ කියන්නේ data ගන්න විතරයි. මේක තමයි හැමදාම අපි browser එකක URL එකක් type කරලා website එකකට යනකොට වෙන්නේ. GET request එකක් Safe මෙන්ම Idempotent ත් වෙනවා. මොකද මේකෙන් server එකේ කිසිම data එකක් වෙනස් වෙන්නේ නැහැ. ඔයා කී සැරයක් request එකක් යැව්වත් ලැබෙන්නේ එකම data set එකමයි.

උදාහරණ:

• GET /users: මේකෙන් system එකේ ඉන්න හැම user කෙනෙක්ගේම list එකක් ගන්න පුළුවන්.
• GET /users/{id}: මේකෙන් specific ID එකක් තියෙන user කෙනෙක්ගේ විස්තර ගන්න පුළුවන්. (උදා: GET /users/123)

// Pseudo-code example for a GET endpoint to get all users
app.get('/api/users', (req, res) => {
    // Database එකෙන් හැම user කෙනෙක්ම ගන්නවා
    const users = db.getAllUsers();
    // 200 OK status code එකත් එක්ක users list එක send කරනවා
    res.status(200).json(users);
});

// Pseudo-code example for a GET endpoint to get a user by ID
app.get('/api/users/:id', (req, res) => {
    const userId = req.params.id; // URL එකෙන් user ID එක ගන්නවා
    // Database එකෙන් අදාළ user ව හොයාගන්නවා
    const user = db.getUserById(userId);
    if (user) {
        res.status(200).json(user);
    } else {
        // User කෙනෙක් නැත්නම් 404 Not Found send කරනවා
        res.status(404).send('User not found');
    }
});

POST Method

POST method එක පාවිච්චි කරන්නේ අලුත් resource එකක් create කරන්න. උදාහරණයක් විදියට, අලුත් user කෙනෙක් system එකට add කරනවා නම් අපි POST request එකක් යවනවා. මේක Safe නැහැ, මොකද මේකෙන් server එකේ data වෙනස් වෙනවා (අලුත් data එකක් add වෙනවා). ඒ වගේම මේක Idempotent නැහැ, මොකද එකම request එක දෙපාරක් යැව්වොත් resource එක දෙපාරක් create වෙන්න පුළුවන් (ඒ කියන්නේ duplicate records හැදෙන්න පුළුවන්).

උදාහරණ:

• POST /users: මේකෙන් body එකේ දාලා තියෙන data ටිකෙන් අලුත් user කෙනෙක් create කරනවා.

// Pseudo-code example for a POST endpoint to create a new user
app.post('/api/users', (req, res) => {
    const newUser = req.body; // Request body එකේ තියෙන user data එක ගන්නවා
    // Basic validation: name සහ email තියෙනවද බලනවා
    if (!newUser.name || !newUser.email) {
        return res.status(400).send('Name and email are required');
    }
    // Database එකට අලුත් user ව add කරනවා
    const createdUser = db.createUser(newUser);
    // 201 Created status code එකත් එක්ක create කරපු user ව send කරනවා
    res.status(201).json(createdUser);
});

PUT Method

PUT method එක පාවිච්චි කරන්නේ existing resource එකක් update කරන්න. මේකෙන් වෙන්නේ දීපු ID එකට අදාළ resource එක සම්පූර්ණයෙන්ම request body එකේ තියෙන data වලින් replace කරන එක. PUT method එක Safe නැහැ, මොකද මේකෙන් server එකේ data වෙනස් වෙනවා. හැබැයි මේක Idempotent වෙනවා, මොකද එකම PUT request එක කී සැරයක් යැව්වත් resource එකේ අවසාන state එක එකම විදියට පවතිනවා.

උදාහරණ:

• PUT /users/{id}: මේකෙන් දීපු ID එකට අදාළ user ව request body එකේ තියෙන data වලින් update කරනවා.

// Pseudo-code example for a PUT endpoint to update an existing user
app.put('/api/users/:id', (req, res) => {
    const userId = req.params.id; // URL එකෙන් user ID එක ගන්නවා
    const updatedUserData = req.body; // Update කරන්න ඕන data එක ගන්නවා
    
    // User කෙනෙක් ඉන්නවද කියලා බලනවා
    const existingUser = db.getUserById(userId);
    if (!existingUser) {
        return res.status(404).send('User not found');
    }
    
    // Database එකේ user ව update කරනවා
    const updatedUser = db.updateUser(userId, updatedUserData);
    res.status(200).json(updatedUser);
});

DELETE Method

DELETE method එක පාවිච්චි කරන්නේ server එකේ තියෙන resource එකක් delete කරන්න. මේක Safe නැහැ, මොකද මේකෙන් server එකේ data වෙනස් වෙනවා (data delete වෙනවා). හැබැයි මේක Idempotent වෙනවා, මොකද resource එක එක සැරයක් delete වුණාට පස්සේ, ඔයා කී සැරයක් DELETE request එක යැව්වත් ඒ resource එක තවදුරටත් delete වෙන්නේ නැහැ (නැත්නම් ඒක නැති බව කියනවා).

උදාහරණ:

• DELETE /users/{id}: මේකෙන් දීපු ID එකට අදාළ user ව delete කරනවා.

// Pseudo-code example for a DELETE endpoint to delete a user
app.delete('/api/users/:id', (req, res) => {
    const userId = req.params.id; // URL එකෙන් user ID එක ගන්නවා

    // User කෙනෙක් ඉන්නවද කියලා බලනවා
    const userExists = db.userExists(userId);
    if (!userExists) {
        return res.status(404).send('User not found');
    }

    // Database එකෙන් user ව delete කරනවා
    db.deleteUser(userId);
    // 204 No Content status code එක send කරනවා (successful delete)
    res.status(204).send(); 
});

User Management API එකක් හදමු - Practical Example

අපි දැන් මේ Methods ටික පාවිච්චි කරලා කොහොමද සරල User Management API එකක් හදාගන්නේ කියලා බලමු. අපි හිතමු අපිට User කෙනෙක්ට id, name, සහ email කියන properties ටික තියෙනවා කියලා. මේක අපි backend framework එකක් (Node.js Express, Python Flask, Java Spring Boot වගේ) පාවිච්චි කරනවා කියලා හිතාගෙන generic pseudo-code වලින් බලමු.

1. GET Users (සියලුම users ලබා ගැනීම සහ එක් user කෙනෙක් ලබා ගැනීම)

Endpoint: GET /api/users
Function: System එකේ ඉන්න සියලුම users ලාගේ list එකක් ලබා දෙනවා.

Endpoint: GET /api/users/{id}
Function: දී ඇති ID එකට අදාළ user ගේ විස්තර ලබා දෙනවා.

උඩ තිබුණ GET method එකට අදාළ pseudo-code එක බලන්න. ඒකෙන් මේ functionality දෙකම cover වෙනවා. status code 200 (OK) එකක් එන්නේ data සාර්ථකව ලැබුණාම, 404 (Not Found) එකක් එන්නේ ඉල්ලපු user කෙනෙක් නැත්නම්.

2. POST User (අලුත් user කෙනෙක් add කිරීම)

Endpoint: POST /api/users
Function: Request body එකේ තියෙන data (name, email) වලින් අලුත් user කෙනෙක් create කරනවා.

POST method එකට අදාළ pseudo-code එකෙන් මේක කරන්න පුළුවන්. successful create එකකට පස්සේ 201 (Created) status code එකක් return කරනවා. Request body එකේ required fields නැත්නම් 400 (Bad Request) වගේ error එකක් දෙන්න පුළුවන්.

3. PUT User (existing user කෙනෙක් update කිරීම)

Endpoint: PUT /api/users/{id}
Function: දී ඇති ID එකට අදාළ user ව request body එකේ තියෙන data වලින් update කරනවා.

PUT method එකට අදාළ pseudo-code එකේ මේක පැහැදිලිව තියෙනවා. update එක සාර්ථක නම් 200 (OK) එකක්, user කෙනෙක් නැත්නම් 404 (Not Found) එකක් return කරනවා.

4. DELETE User (user කෙනෙක් delete කිරීම)

Endpoint: DELETE /api/users/{id}
Function: දී ඇති ID එකට අදාළ user ව system එකෙන් delete කරනවා.

DELETE method එකට අදාළ pseudo-code එකෙන් මේක කරන්න පුළුවන්. සාර්ථකව delete වුණාම 204 (No Content) status code එකක් return කරනවා. 204 කියන්නේ request එක සාර්ථකයි, හැබැයි response body එකේ send කරන්න data එකක් නැහැ කියන එක.

වැදගත් දේවල් මතක තියාගමු

• Status Codes: හැම request එකකටම server එකෙන් status code එකක් එනවා. මේවායින් request එකේ outcome එක ගැන දැනගන්න පුළුවන්. 200 Family (2xx) සාර්ථකත්වය, 400 Family (4xx) Client side errors, 500 Family (5xx) Server side errors පෙන්නනවා. 200 OK, 201 Created, 204 No Content, 400 Bad Request, 404 Not Found, 500 Internal Server Error මේවා අතරින් බහුලව පාවිච්චි වෙනවා.
• Resource-Oriented URLs: REST API එකක URL (Endpoint) හදද්දී resources (නාම පද) පාවිච්චි කරන්න ඕන. උදා: /users, /products වගේ. ක්‍රියා පද (verbs) URL එකේ නැතුව HTTP Methods (GET, POST, PUT, DELETE) වලින් ක්‍රියාව පෙන්නන්න ඕන.
• Statelessness: REST API එකක් Stateless වෙන්න ඕන. ඒ කියන්නේ, server එක client එකේ පෙර request එකකින් කිසිම information එකක් මතක තියාගන්නේ නැහැ. හැම request එකක්ම තනිවම තේරුම් ගන්න පුළුවන් වෙන්න ඕන.
• Error Handling: API එකක් හදද්දී, errors handle කරන එක ඉතා වැදගත්. වැරදි data ආවොත්, ඉල්ලපු resource එක නැත්නම්, server එකේ ප්‍රශ්නයක් ආවොත් ඒවට අදාළ status codes සහ clear error messages send කරන්න ඕන.

නිගමනය

හරි, අදට ඇති කියලා හිතනවා. අපි අද REST API වල heartbeat එක වගේ තියෙන HTTP Methods ගැනත්, ඒ ටික පාවිච්චි කරලා කොහොමද සරල User CRUD API එකක් හදාගන්නේ කියලාත් හොඳට ඉගෙනගත්තා. මේ GET, POST, PUT, DELETE methods ටික නිවැරදිව පාවිච්චි කරන එක හොඳ RESTful API එකක් design කරන්න අත්‍යවශ්‍යයි. Idempotency, Safety, Status Codes කියන concepts ඔයාලට තේරුණා කියලා හිතනවා.

දැන් ඔයාලට පුළුවන් මේ concepts තේරුම් අරන් ඔයාලගේම project වලට මේවා implement කරන්න බලන්න. මේ pseudo-code ටික තමන් කැමති programming language එකකින් (Node.js, Python, Java වගේ) real project එකකට apply කරලා බලන්න. එතකොට තමයි මේක හොඳටම ඔලුවට යන්නේ. මේ article එක ගැන ඔයාලගේ අදහස්, ප්‍රශ්න පහළින් comment එකක් දාලා කියන්න. අපි ඊළඟ article එකකින් හම්බවෙමු! සුභ දවසක්!