By Thisara Priyamal — 24 Aug 2025

Python Flask-RESTful API Development Sinhala Tutorial

දැන් තියෙන ලෝකේ හැම Software Application එකක්ම වගේ එකිනෙකා එක්ක කතා කරනවා. මේ කතා කරන්න ගොඩක්ම පාවිච්චි කරන ක්‍රමයක් තමයි RESTful APIs. ඔයාගේ Mobile App එකක්, Web Application එකක්, එහෙමත් නැත්නම් වෙනත් Backend Service එකක් වුණත්, ඒවාට Data අරගන්න, Data යවන්න, APIs නැතුව බෑ. අද අපි Python වල Flask Framework එකත්, Flask-RESTful Library එකත් පාවිච්චි කරලා කොහොමද Powerful RESTful API එකක් හදාගන්නේ කියලා බලමු. මේ Tutorial එක ඉවරවෙනකොට, ඔයාට පුළුවන් වෙයි To-Do List Application එකක් සඳහා Backend API එකක් සාදාගන්න. ඔයා Fresher Developer කෙනෙක්ද? එහෙනම් මේක ඔයාටමයි!

RESTful APIs කියන්නේ මොනවද?

සරලව කිව්වොත්, API (Application Programming Interface) එකක් කියන්නේ වෙනස් Software දෙකක් අතරේ සම්බන්ධයක් ඇති කරන විදිහක්. REST (Representational State Transfer) කියන්නේ මේ APIs හදන විදිහ ගැන තියෙන architectural style එකක්. මේක Protocol එකක් නෙවෙයි, Guidelines ටිකක්.

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

Client-Server: Client (ඔයාගේ Browser, Mobile App එක) සහ Server (API එක තියෙන තැන) කියන දෙක වෙන වෙනම වැඩ කරනවා. ඒ නිසා එකිනෙකාට බලපෑමක් නැතුව දියුණු කරන්න පුළුවන්.
Stateless: Server එකට Client ගෙන් එන හැම Request එකක්ම ස්වාධීනයි. කලින් ආපු Request එකක තොරතුරු Server එක මතක තියාගන්නේ නෑ. හැම Request එකකටම අවශ්‍ය හැම විස්තරයක්ම අඩංගු වෙන්න ඕනේ.
Cacheable: Client පැත්තෙන් Server එකට යන Request අතරින් සමහර ඒවා Cache කරන්න පුළුවන් කියලා Server එකට කියන්න පුළුවන්. ඒකෙන් Performance වැඩි වෙනවා.
Uniform Interface: API එකක් කොහොමද වැඩ කරන්නේ කියලා දැනගන්න පොදු ක්‍රමයක් තියෙන්න ඕනේ. (උදා: HTTP Methods, Resource Identifiers).
Layered System: Client ට තේරෙන්නේ නෑ Server එකට කලින් තව Servers (Proxy Servers, Load Balancers) තියෙනවද කියලා.

HTTP Methods - API එකේ ක්‍රියා (Actions)

RESTful API එකක Resources (Data) එක්ක වැඩ කරන්න අපි HTTP Methods පාවිච්චි කරනවා. මේවා තමයි ප්‍රධාන ඒවා:

GET: Server එකෙන් Data ලබා ගැනීමට (Retrieve data).
POST: Server එකට අලුත් Data යැවීමට (Create new data).
PUT: Server එකේ තියෙන Data update කරන්න / replace කරන්න (Update/Replace existing data).
DELETE: Server එකෙන් Data මකා දැමීමට (Delete data).
PATCH: Server එකේ තියෙන Data වල කොටසක් update කරන්න (Partial update).

JSON (JavaScript Object Notation) Data Format

API එකකදී Client සහ Server අතරේ Data හුවමාරු වෙන්නේ JSON Format එකෙන්. මේක කියවන්න සහ ලියන්න පහසු Text-based Format එකක්. Python වල dictionary එකකට ගොඩක් සමානයි.

{
  "id": "1",
  "task": "ගෙදර වැඩ කරන්න",
  "completed": false
}

Flask සහ Flask-RESTful

Flask: Python වල තියෙන light-weight web framework එකක්. මේකෙන් Web Applications, APIs හදන්න පුළුවන්.
Flask-RESTful: Flask වලට උඩින් හදපු Extension එකක්. මේකෙන් RESTful APIs හදන එක තවත් පහසු කරනවා. Resource කියන Concept එක මේකෙන් ගොඩක් ලේසි කරනවා.

අපි To-Do List API එකක් හදමු!

දැන් අපි Python Flask-RESTful පාවිච්චි කරලා සරල To-Do List API එකක් හදමු. මේ API එකෙන් To-Do Tasks, create කරන්න, read කරන්න, update කරන්න, delete කරන්න (CRUD Operations) පුළුවන්.

පියවර 1: අවශ්‍ය Libraries Install කරගනිමු

ඔයාගේ Terminal එක Open කරලා මේ Commands ටික Run කරන්න:

pip install Flask Flask-RESTful

පියවර 2: මූලික Setup එක

app.py කියලා File එකක් හදලා මේ Code එක Copy කරන්න. අපි මේ API එකේ Data Save කරන්න තාවකාලිකව Python dictionary එකක් පාවිච්චි කරනවා. Real-world Project වලදී Database එකක් (SQLite, PostgreSQL, MongoDB) පාවිච්චි කරනවා.

from flask import Flask, request
from flask_restful import Resource, Api

# Flask Application එක Initialize කරනවා
app = Flask(__name__)
# Flask-RESTful API එක Initialize කරනවා
api = Api(app)

# තාවකාලිකව Data Save කරගන්න Python Dictionary එකක්
# { '1': {'task': 'ගෙදර වැඩ කරන්න', 'status': 'pending'} }
tasks = {}
# අලුත් Task එකකට ID එකක් දෙන්න Counter එකක්
task_id_counter = 1

# API එකේ Root URL එකට Request එකක් ආවම දෙන Response එක
@app.route('/')
def home():
    return "<h1>Welcome to the To-Do API!</h1><p>Use /tasks endpoint for task management.</p>"

පියවර 3: Tasks List එක Manage කරන Resource එක හදමු (`/tasks`)

මේ TaskList Resource එකෙන් අපිට පුළුවන් හැම Tasks එකක්ම ලබා ගන්න (GET) සහ අලුත් Task එකක් Create කරන්න (POST).

class TaskList(Resource):
    # හැම Task එකක්ම ලබා ගැනීමට
    def get(self):
        return tasks, 200 # tasks dictionary එක සහ HTTP 200 OK status code එක return කරනවා

    # අලුත් Task එකක් Add කිරීමට
    def post(self):
        global task_id_counter # global counter එක update කරන්න
        
        # Request එකේ body එක JSON Format එකෙන් තියෙනවද සහ 'task' field එක තියෙනවද බලනවා
        if not request.json or 'task' not in request.json:
            return {"message": "Invalid request body. 'task' field is required."}, 400 # 400 Bad Request

        task_id = str(task_id_counter)
        tasks[task_id] = {"task": request.json['task'], "status": "pending"}
        task_id_counter += 1
        return {"id": task_id, "task": tasks[task_id]['task'], "status": tasks[task_id]['status']}, 201 # 201 Created

# /tasks කියන URL එකට TaskList Resource එක Add කරනවා
api.add_resource(TaskList, '/tasks')

පියවර 4: තනි Task එකක් Manage කරන Resource එක හදමු (`/tasks/`)

මේ Task Resource එකෙන් අපිට පුළුවන් නිශ්චිත Task එකක් ලබා ගන්න (GET), Update කරන්න (PUT) සහ Delete කරන්න (DELETE).

class Task(Resource):
    # නිශ්චිත Task එකක් ලබා ගැනීමට
    def get(self, task_id):
        if task_id not in tasks:
            return {"message": "Task not found."}, 404 # 404 Not Found
        return tasks[task_id], 200

    # නිශ්චිත Task එකක් Update කිරීමට
    def put(self, task_id):
        if task_id not in tasks:
            return {"message": "Task not found."}, 404
        if not request.json or 'task' not in request.json:
            return {"message": "Invalid request body. 'task' field is required."}, 400

        tasks[task_id]['task'] = request.json['task']
        if 'status' in request.json: # status එකත් update කරන්න පුළුවන්
            tasks[task_id]['status'] = request.json['status']
        return {"message": "Task updated successfully.", "task": tasks[task_id]}, 200

    # නිශ්චිත Task එකක් Delete කිරීමට
    def delete(self, task_id):
        if task_id not in tasks:
            return {"message": "Task not found."}, 404
        del tasks[task_id]
        return {"message": "Task deleted successfully."}, 204 # 204 No Content

# /tasks/<task_id> කියන URL එකට Task Resource එක Add කරනවා
api.add_resource(Task, '/tasks/<string:task_id>')

# Application එක Run කරන්න
if __name__ == '__main__':
    app.run(debug=True) # debug=True එකෙන් Development වලදී Errors බලාගන්න පුළුවන්

පියවර 5: API එක Test කරමු!

Terminal එකේදී python app.py කියලා Run කරන්න. ඊට පස්සේ Postman, Insomnia, නැත්නම් cURL වගේ Tool එකක් පාවිච්චි කරලා API එක Test කරන්න පුළුවන්.

උදාහරණ:

GET All Tasks:
Method: GET
URL: http://127.0.0.1:5000/tasks
POST a New Task:
Method: POST
URL: http://127.0.0.1:5000/tasks
Body (JSON): {"task": "පළතුරු කඩෙන් ගන්න", "status": "pending"}
GET a Specific Task:
Method: GET
URL: http://127.0.0.1:5000/tasks/1 (1 කියන්නේ Task ID එක)
PUT (Update) a Task:
Method: PUT
URL: http://127.0.0.1:5000/tasks/1
Body (JSON): {"task": "පළතුරු කඩෙන් ගෙනාවා", "status": "completed"}
DELETE a Task:
Method: DELETE
URL: http://127.0.0.1:5000/tasks/1

HTTP Status Codes සහ Error Handling

API එකකදී, හැම Request එකකටම Response එකක් එක්ක HTTP Status Code එකක් එනවා. මේවායින් Client එකට කියනවා Request එකට මොකද වුණේ කියලා. මේවා හරියට පාවිච්චි කරන එක ඉතා වැදගත්.

නිතර භාවිතා වන Status Codes:

200 OK: Request එක සාර්ථකයි. (GET, PUT වලට)
201 Created: අලුත් Resource එකක් සාර්ථකව නිර්මාණය කළා. (POST වලට)
204 No Content: Request එක සාර්ථකයි, නමුත් Response එකේ Body එකක් නෑ. (DELETE වලට)
400 Bad Request: Client පැත්තෙන් ආපු Request එක වැරදියි (උදා: අවශ්‍ය Fields නැහැ).
401 Unauthorized: Client ට මේ Resource එකට Access කරන්න අවසර නෑ (Authentication නැහැ).
403 Forbidden: Client Authenticate වෙලා තිබුණත්, මේ ක්‍රියාව කරන්න අවසර නෑ (Authorization නැහැ).
404 Not Found: ඉල්ලපු Resource එක Server එකේ නැහැ.
500 Internal Server Error: Server පැත්තෙන් යම්කිසි දෝෂයක්.

Flask-RESTful වල Error Handling

අපි මේ Tutorial එකේදී return {"message": "..."}, status_code වගේ Statement පාවිච්චි කරලා Error Handling කරා. Complex Scenarios වලදී, Flask-RESTful වල abort function එක පාවිච්චි කරන්න පුළුවන්. request.json වගේ Request Body එක validate කරන්න marshmallow වගේ Library එකක් පාවිච්චි කරන එක Professional API වලට ගොඩක් වැදගත්.

Best Practices සහ අමතර Tips

හොඳ API එකක් හදනවා කියන්නේ වැඩ කරන එකක් හදනවට වඩා දෙයක්. ඒක Maintain කරන්න ලේසි වෙන්නත් ඕනේ.

Consistent API Design

URLs: Resources වලට Noun (නාම පද) පාවිච්චි කරන්න, Verb (ක්‍රියා පද) නෙවෙයි. Plural form එකෙන් (බහු වචනයෙන්) භාවිතා කරන්න. (උදා: /tasks, /users මිසක් /getTasks, /createUser නෙවෙයි).
HTTP Methods: හැමවිටම නිවැරදි HTTP Method එක, අදාළ ක්‍රියාවට පාවිච්චි කරන්න (GET for retrieve, POST for create, etc.).
Versioning: API එකේ Versioning පාවිච්චි කරන්න (උදා: /v1/tasks). මේකෙන් API එකේ වෙනස්කම් කරද්දී Backwards Compatibility එක Maintain කරන්න පුළුවන්.
Error Messages: Clear, informative error messages දෙන්න.

Authentication සහ Authorization

ඔයාගේ API එක Public නම් ගැටලුවක් නැහැ, නමුත් Usersලගේ Data වගේ Critical Data Manage කරනවා නම්, Authentication (User කවුද කියලා තහවුරු කිරීම) සහ Authorization (User ට මොනවද කරන්න අවසර තියෙන්නේ කියලා තීරණය කිරීම) අනිවාර්යයි. JWT (JSON Web Tokens), OAuth වගේ දේවල් මේකට පාවිච්චි කරනවා.

Database Integration

අපි මේ Project එකේදී Data Save කරන්න Python dictionary එකක් පාවිච්චි කළා. Real-world Project වලදී SQLite, PostgreSQL, MySQL, MongoDB වගේ Databases පාවිච්චි කරන්න ඕනේ. Python වලට SQLAlchemy (SQL Databases වලට) නැත්නම් MongoEngine (MongoDB වලට) වගේ ORMs/ODMs පාවිච්චි කරන්න පුළුවන්.

API Testing

හදන API එක හරියට වැඩ කරනවද කියලා බලන්න Unit Tests සහ Integration Tests ලියන එක ඉතා වැදගත්. මේවායින් Future එකේදී Code එකේ වෙනස්කම් කරද්දී Problems එනවද කියලා Check කරන්න පුළුවන්.

අවසන් වචන

අද අපි Python Flask-RESTful භාවිතයෙන් RESTful API එකක් මුල සිට හදන හැටි ඉගෙන ගත්තා. REST මූලික සිද්ධාන්ත, HTTP Methods, JSON Data Format එක, ඒ වගේම Flask-RESTful Framework එකේ මූලික භාවිතය සහ To-Do List API එකක් සාදාගෙන එය Test කරන ආකාරය ගැනත් අපි සාකච්ඡා කළා. ඒ වගේම Status Codes සහ Best Practices ටිකකුත් අපි Review කළා.

දැන් ඔයාට හොඳ අවබෝධයක් තියෙනවා RESTful API එකක් කියන්නේ මොකක්ද සහ Flask-RESTful වලින් ඒක කොහොමද හදන්නේ කියලා. මේක ඔයාගේ Web Development Journey එකේ වැදගත් පියවරක් වේවි. තවත් දියුණු වෙන්න නම්, අපි මේ හදපු To-Do API එක ඔයාගේම Project එකක දාලා බලන්න. Database එකක් Connect කරලා, Authentication එකකුත් දාලා තවත් දියුණු කරන්න පුළුවන්.

මේ Tutorial එක ගැන ඔයාගේ අදහස්, ප්‍රශ්න පහල Comment Section එකේ දාන්න අමතක කරන්න එපා. අපි ලංකාවේ Developersලා විදිහට එකතු වෙලා දියුණු වෙමු!