بناء JSON API بـ Flask

بناء JSON API بـ Flask — Building a JSON API with Flask

الخادم الذي يُعيد نصاً عادياً مفيد، لكن الإنترنت الحديث يتحدث JSON. كل تطبيق موبايل، كل موقع React، كل خدمة تحتاج بيانات — كلها تتوقع JSON. في هذا الدرس، ستبني API حقيقي يستقبل JSON ويُعيد JSON، باتباع أنماط REST المعتمدة في الصناعة.

مفهوم REST

REST (Representational State Transfer) ليس بروتوكولاً بل مجموعة مبادئ تصميم لـ APIs:

الأسلوب	المسار	العملية
GET	`/books`	اقرأ قائمة الكتب
GET	`/books/1`	اقرأ كتاباً واحداً
POST	`/books`	أنشئ كتاباً جديداً
PUT	`/books/1`	حدّث كتاباً كاملاً
DELETE	`/books/1`	احذف كتاباً

هذا النمط متفق عليه عالمياً — أي مطور يفهمه فور رؤيته.

`jsonify` — تحويل Python إلى JSON

دالة jsonify تُحوّل أي dict أو list إلى استجابة HTTP بصيغة JSON مع الترويسات الصحيحة تلقائياً:

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/api/version")
def version():
    return jsonify({
        "version": "1.0.0",
        "name": "كتبي API"
    })
# الاستجابة: {"version": "1.0.0", "name": "كتبي API"}
# مع Content-Type: application/json

`request.get_json()` — قراءة JSON من الطلب

عندما يُرسل العميل بيانات JSON في جسم الطلب، request.get_json() يحوّلها إلى dict:

from flask import Flask, request, jsonify

@app.route("/api/books", methods=["POST"])
def create_book():
    data = request.get_json()   # تحويل JSON إلى dict — JSON to dict
    if not data:
        return jsonify({"error": "بيانات مطلوبة"}), 400
    
    title = data.get("title")
    author = data.get("author")
    # ... حفظ الكتاب — save the book

بناء API الكتب — خطوة بخطوة

سنبني API كاملاً لإدارة مكتبة. سنبدأ بالهيكل الأساسي ونضيف عليه تدريجياً.

الخطوة 1: هيكل البيانات والمسار الأول

main.go

import micropip
await micropip.install("flask")
from flask import Flask, jsonify

app = Flask(__name__)

# تخزين الكتب في الذاكرة — In-memory book store
books = [
    {"id": 1, "title": "ألف ليلة وليلة", "author": "مجهول", "year": 850},
    {"id": 2, "title": "كليلة ودمنة", "author": "ابن المقفع", "year": 750},
    {"id": 3, "title": "المقدمة", "author": "ابن خلدون", "year": 1377}
]

# GET /api/books — قائمة جميع الكتب — List all books
@app.route("/api/books")
def list_books():
    return jsonify({
        "count": len(books),
        "books": books
    })

with app.test_client() as client:
    r = client.get("/api/books")
    import json
    data = json.loads(r.get_data(as_text=True))
    print(f"رمز الحالة: {r.status_code}")
    print(f"عدد الكتب: {data['count']}")
    for book in data["books"]:
        print(f"  [{book['id']}] {book['title']} — {book['author']}")

Output:

الخطوة 2: مسار كتاب واحد مع معالجة الخطأ

main.go

import micropip
await micropip.install("flask")
from flask import Flask, jsonify

app = Flask(__name__)

books = [
    {"id": 1, "title": "ألف ليلة وليلة", "author": "مجهول", "year": 850},
    {"id": 2, "title": "كليلة ودمنة", "author": "ابن المقفع", "year": 750}
]

# GET /api/books/<id> — كتاب واحد — Single book
@app.route("/api/books/<int:book_id>")
def get_book(book_id):
    # ابحث عن الكتاب — Find the book
    book = next((b for b in books if b["id"] == book_id), None)
    
    if book is None:
        # 404 إذا لم يوجد — 404 if not found
        return jsonify({"error": f"لا يوجد كتاب بمعرّف {book_id}"}), 404
    
    return jsonify(book)

with app.test_client() as client:
    import json
    
    # كتاب موجود — Existing book
    r1 = client.get("/api/books/1")
    book = json.loads(r1.get_data(as_text=True))
    print(f"[{r1.status_code}] {book['title']}")
    
    # كتاب غير موجود — Non-existent book
    r2 = client.get("/api/books/99")
    err = json.loads(r2.get_data(as_text=True))
    print(f"[{r2.status_code}] {err['error']}")

Output:

الخطوة 3: إنشاء كتاب جديد (POST)

استقبال JSON من الطلب يتطلب أن يُرسل العميل Content-Type: application/json في الترويسة. مع test_client، نستخدم content_type="application/json":

main.go

import micropip
await micropip.install("flask")
from flask import Flask, jsonify, request
import json

app = Flask(__name__)

books = [
    {"id": 1, "title": "ألف ليلة وليلة", "author": "مجهول", "year": 850}
]
next_id = 2  # عداد المعرّفات — ID counter

@app.route("/api/books", methods=["GET"])
def list_books():
    return jsonify({"count": len(books), "books": books})

@app.route("/api/books", methods=["POST"])
def create_book():
    global next_id
    
    data = request.get_json()
    
    # تحقق من البيانات — Validate data
    if not data:
        return jsonify({"error": "البيانات مطلوبة"}), 400
    if not data.get("title"):
        return jsonify({"error": "العنوان مطلوب"}), 400
    if not data.get("author"):
        return jsonify({"error": "المؤلف مطلوب"}), 400
    
    # إنشاء الكتاب — Create the book
    new_book = {
        "id": next_id,
        "title": data["title"],
        "author": data["author"],
        "year": data.get("year", 0)
    }
    books.append(new_book)
    next_id += 1
    
    # 201 Created للإنشاء الناجح — 201 Created for successful creation
    return jsonify(new_book), 201

with app.test_client() as client:
    # عدد الكتب قبل الإضافة — Book count before adding
    r0 = client.get("/api/books")
    before = json.loads(r0.get_data(as_text=True))
    print(f"قبل: {before['count']} كتب")
    
    # إضافة كتاب جديد — Add new book
    new = {"title": "رسالة الغفران", "author": "المعري", "year": 1033}
    r1 = client.post("/api/books",
                     data=json.dumps(new),
                     content_type="application/json")
    created = json.loads(r1.get_data(as_text=True))
    print(f"[{r1.status_code}] أُنشئ: {created['title']} (id={created['id']})")
    
    # عدد الكتب بعد الإضافة — Book count after adding
    r2 = client.get("/api/books")
    after = json.loads(r2.get_data(as_text=True))
    print(f"بعد: {after['count']} كتب")

Output:

الخطوة 4: حذف كتاب (DELETE)

main.go

import micropip
await micropip.install("flask")
from flask import Flask, jsonify, request
import json

app = Flask(__name__)

books = [
    {"id": 1, "title": "ألف ليلة وليلة", "author": "مجهول", "year": 850},
    {"id": 2, "title": "كليلة ودمنة", "author": "ابن المقفع", "year": 750},
    {"id": 3, "title": "المقدمة", "author": "ابن خلدون", "year": 1377}
]

@app.route("/api/books")
def list_books():
    return jsonify({"count": len(books), "books": [b["title"] for b in books]})

@app.route("/api/books/<int:book_id>", methods=["DELETE"])
def delete_book(book_id):
    global books
    
    # ابحث عن الكتاب — Find the book
    book = next((b for b in books if b["id"] == book_id), None)
    if book is None:
        return jsonify({"error": f"لا يوجد كتاب بمعرّف {book_id}"}), 404
    
    # احذفه — Delete it
    books = [b for b in books if b["id"] != book_id]
    
    # 200 مع تأكيد — 200 with confirmation
    return jsonify({"message": f"حُذف: {book['title']}"})

with app.test_client() as client:
    # القائمة قبل الحذف — List before deletion
    r0 = client.get("/api/books")
    before = json.loads(r0.get_data(as_text=True))
    print(f"قبل: {before['count']} — {before['books']}")
    
    # حذف كتاب موجود — Delete existing book
    r1 = client.delete("/api/books/2")
    msg = json.loads(r1.get_data(as_text=True))
    print(f"[{r1.status_code}] {msg['message']}")
    
    # محاولة حذف غير موجود — Try to delete non-existent
    r2 = client.delete("/api/books/99")
    err = json.loads(r2.get_data(as_text=True))
    print(f"[{r2.status_code}] {err['error']}")
    
    # القائمة بعد الحذف — List after deletion
    r3 = client.get("/api/books")
    after = json.loads(r3.get_data(as_text=True))
    print(f"بعد: {after['count']} — {after['books']}")

Output:

استجابات الخطأ الموحدة

في APIs الاحترافية، جميع الأخطاء تتبع نفس الشكل:

# شكل الخطأ الموحد — Unified error shape
def error_response(message, code):
    return jsonify({
        "error": message,
        "code": code
    }), code

# الاستخدام — Usage
return error_response("المورد غير موجود", 404)
return error_response("بيانات غير صالحة", 400)
return error_response("غير مصرح", 401)

هذا يجعل العملاء (تطبيقات الموبايل، الويب) يعرفون دائماً أين يجدون رسالة الخطأ.

التحديات التطبيقية

الآن حان وقت البناء المستقل. هذه التحديات تبني API للكتب تدريجياً — كل تحدٍّ يُضيف ميزة جديدة.

تحدي — Challenge

import micropip
await micropip.install("flask")
from flask import Flask, jsonify
import json

app = Flask(__name__)

books = [
    {"id": 1, "title": "ألف ليلة وليلة", "author": "مجهول"},
    {"id": 2, "title": "كليلة ودمنة", "author": "ابن المقفع"}
]

# عرّف GET /api/books يُعيد {"count": N, "books": [...]}
# Define GET /api/books returning {"count": N, "books": [...]}

# اكتب الكود هنا — Write your code here

with app.test_client() as client:
    r = client.get("/api/books")
    data = json.loads(r.get_data(as_text=True))
    print(f"[{r.status_code}] {data['count']}")
    for b in data["books"]:
        print(b["title"])

تحدي — Challenge

import micropip
await micropip.install("flask")
from flask import Flask, jsonify, request
import json

app = Flask(__name__)

books = []
next_id = 1

# عرّف POST /api/books
# يقرأ {"title": "...", "author": "..."} من جسم الطلب
# يتحقق: إذا لم يوجد title أعد {"error": "العنوان مطلوب"} برمز 400
# عند النجاح: أضف الكتاب وأعد {"id": ..., "title": ...} برمز 201

# اكتب الكود هنا — Write your code here

with app.test_client() as client:
    # طلب ناجح — Successful request
    r1 = client.post("/api/books",
                     data=json.dumps({"title": "رسالة الغفران", "author": "المعري"}),
                     content_type="application/json")
    d1 = json.loads(r1.get_data(as_text=True))
    print(f"[{r1.status_code}] {d1['title']}")
    
    # طلب ناقص — Missing title
    r2 = client.post("/api/books",
                     data=json.dumps({"author": "مجهول"}),
                     content_type="application/json")
    d2 = json.loads(r2.get_data(as_text=True))
    print(f"[{r2.status_code}] {d2['error']}")

تحدي — Challenge

import micropip
await micropip.install("flask")
from flask import Flask, jsonify
import json

app = Flask(__name__)

books = [
    {"id": 1, "title": "ألف ليلة وليلة", "author": "مجهول"},
    {"id": 2, "title": "المقدمة", "author": "ابن خلدون"}
]

# عرّف GET /api/books/<int:book_id>
# ابحث عن الكتاب وأعده، أو أعد {"error": "لا يوجد كتاب بمعرّف <id>"} برمز 404

# اكتب الكود هنا — Write your code here

with app.test_client() as client:
    r1 = client.get("/api/books/2")
    d1 = json.loads(r1.get_data(as_text=True))
    print(f"[{r1.status_code}] {d1['title']}")
    
    r2 = client.get("/api/books/99")
    d2 = json.loads(r2.get_data(as_text=True))
    print(f"[{r2.status_code}] {d2['error']}")

تحدي — Challenge

import micropip
await micropip.install("flask")
from flask import Flask, jsonify
import json

app = Flask(__name__)

books = [
    {"id": 1, "title": "ألف ليلة وليلة", "author": "مجهول"},
    {"id": 2, "title": "كليلة ودمنة", "author": "ابن المقفع"}
]

@app.route("/api/books")
def list_books():
    return jsonify({"count": len(books)})

# عرّف DELETE /api/books/<int:book_id>
# احذف الكتاب وأعد {"message": "حُذف: <title>"}
# إذا لم يوجد: {"error": "لا يوجد كتاب بمعرّف <id>"} برمز 404

# اكتب الكود هنا — Write your code here

with app.test_client() as client:
    # حذف كتاب موجود — Delete existing
    r1 = client.delete("/api/books/2")
    d1 = json.loads(r1.get_data(as_text=True))
    print(f"[{r1.status_code}] {d1['message']}")
    
    # التحقق من العدد — Verify count
    r2 = client.get("/api/books")
    d2 = json.loads(r2.get_data(as_text=True))
    print(f"[{r2.status_code}] {d2['count']}")
    
    # حذف غير موجود — Delete non-existent
    r3 = client.delete("/api/books/2")
    d3 = json.loads(r3.get_data(as_text=True))
    print(f"[{r3.status_code}] {d3['error']}")

بناء JSON API بـ Flask