واجهات RESTful API

طريقان إلى نفس الفكرة

الأساسيات المطلوبة

المفاهيم الأساسية

الواجهة البرمجية (API) عقد بين برنامجين: «أرسل لي طلبًا بهذا الشكل أعطك ردًا بذاك». و REST أسلوب لتصميم هذا العقد فوق HTTP بحيث يكون موحّدًا ويسهل توسّعه.

1ما هو REST؟ القيود الستة

صاغ Roy Fielding هذه القيود في أطروحته. الواجهة التي تحترمها تسمى RESTful:

2تشريح HTTP: الطلب والرد

POST /drinks HTTP/1.1                       <- سطر الطلب: المنهج + المسار + الإصدار
Host: localhost:5055                        <- ترويسات (Headers)
Content-Type: application/json
Authorization: Bearer <token>
                                            <- سطر فارغ
{"name": "V60", "price_halalas": 1800}      <- الجسم (Body)

HTTP/1.1 201 CREATED                        <- سطر الحالة: الإصدار + الرمز + العبارة
Content-Type: application/json
Location: /drinks/3
                                            <- سطر فارغ
{"id": 3, "name": "V60", "price_halalas": 1800}

العنوان URL نفسه له أجزاء: https://api.cafe.example:443/drinks/2?size=large#top = المخطط (https) + المضيف + المنفذ + المسار + معاملات الاستعلام (بعد ?) + الجزء (بعد # ولا يصل إلى الخادم أصلًا).

3HTTP مقابل HTTPS

HTTPS هو HTTP نفسه داخل قناة مشفّرة بـTLS. يعطيك ثلاثة أشياء: سرّية (لا يقرأ الوسطاء المحتوى)، سلامة (لا يعدّله أحد دون كشف)، وهوية الخادم (شهادة تثبت أنك تكلّم الموقع الصحيح). المنفذ الافتراضي 80 لـHTTP و443 لـHTTPS. لاحظ أنه يحمي الطريق لا الخادم: واجهة سيئة التصميم تبقى سيئة فوق HTTPS.

4المناهج (Methods): الفعل المطلوب

آمن = لا يغيّر حالة الخادم. متكافئ = تكرار الطلب عدة مرات له نفس أثر مرة واحدة: حذف المشروب 2 مرتين يترك الحالة النهائية نفسها (وقد يتغير الرد من 204 إلى 404). أما POST فتكراره ينشئ نسخًا جديدة، ولهذا يحذر العملاء من إعادة إرساله تلقائيًا بعد انقطاع.

5رموز الحالة (Status Codes)

6تصميم الموارد والروابط

7استهلاك واجهة من سطر الأوامر: curl

8استهلاك واجهة من بايثون: requests

9بناء واجهة: http.server ثم Flask

http.server في المكتبة القياسية يريك الآلية عارية: صنف ترثه وتكتب do_GET و do_POST‏، وتصيغ الرد بيدك (send_response ثم send_header ثم end_headers ثم الكتابة في wfile). لا يوجد توجيه ولا تحقق ولا تحويل JSON، وتوثيق بايثون نفسه يحذّر بأنه غير موصى به للإنتاج ويطبّق فحوصًا أمنية أساسية فقط. Flask يعطيك ما ينقصه: جدول توجيه بالمزخرفات، ومحوّلات للمسار مثل <int:drink_id>‏، و jsonify‏، ومعالجات أخطاء.

الأمن والمصادقة

1️⃣1️⃣ التوثيق والمعايير: OpenAPI

OpenAPI (كان اسمه Swagger Specification) صيغة YAML أو JSON تصف الواجهة: المسارات والمناهج والمعاملات وشكل الطلب والرد والمصادقة. الميزة أنها مقروءة للبشر والآلات معًا: من الملف نفسه تُولَّد صفحة توثيق تفاعلية (Swagger UI)، وعملاء جاهزون، وهياكل خوادم، وتُفحص الردود تلقائيًا في الاختبارات.

كيف تعمل الواجهة خطوة بخطوة؟

أربع صور: مسار طلب واحد من العميل إلى الخادم، شجرة اختيار رمز الحالة، الفرق بين http.server و Flask، وتذكرة المصادقة.

الرسم 32: رحلة طلب إنشاء: الرد يحمل 201 وعنوان المورد الجديد في Location ليعرف العميل أين يجده.

الرسم 33: شجرة اختيار رمز الحالة: اسأل الأسئلة بهذا الترتيب (الهوية، فالصلاحية، فصحة المدخل، فوجود المورد) فيخرج الرمز الصحيح تلقائيًا.

الرسم 34: نفس المهمة بمسارين: في http.server أنت تبني كل خطوة، وفي Flask الإطار يبني التوجيه والترميز ويترك لك منطق العمل.

الرسم 35: تذكرة المصادقة: تُصدر مرة بعد تسجيل الدخول وتُرسل مع كل طلب لاحق، ولا يحتفظ الخادم بجلسة بين الطلبات.

مثال تطبيقي: واجهة قائمة المقهى من الصفر

نبني واجهة قائمة مقهانا (/drinks) ونجرّبها بالأدوات الثلاث. كل الأكواد والمخرجات التالية جُرّبت فعليًا.

الخطوة 1: صمّم الموارد قبل أن تكتب سطرًا

الخطوة 2: الخادم بـFlask

from flask import Flask, jsonify, request

app = Flask(__name__)
drinks = {1: {"id": 1, "name": "Flat White", "price_halalas": 1400},
          2: {"id": 2, "name": "Cortado", "price_halalas": 1200}}
next_id = 3

@app.get("/drinks")
def list_drinks():
    return jsonify(list(drinks.values()))

@app.get("/drinks/<int:drink_id>")
def get_drink(drink_id):
    drink = drinks.get(drink_id)
    if drink is None:
        return jsonify(error="drink not found"), 404
    return jsonify(drink)

@app.post("/drinks")
def create_drink():
    global next_id
    data = request.get_json(silent=True)
    if not data or "name" not in data or not isinstance(data.get("price_halalas"), int):
        return jsonify(error="name and integer price_halalas are required"), 400
    drink = {"id": next_id, "name": data["name"], "price_halalas": data["price_halalas"]}
    drinks[next_id] = drink
    next_id += 1
    resp = jsonify(drink)
    resp.status_code = 201
    resp.headers["Location"] = f"/drinks/{drink['id']}"
    return resp

@app.delete("/drinks/<int:drink_id>")
def delete_drink(drink_id):
    if drinks.pop(drink_id, None) is None:
        return jsonify(error="drink not found"), 404
    return "", 204

if __name__ == "__main__":
    app.run(port=5055)

الخطوة 3: جرّبه بـcurl

$ curl -i localhost:5055/drinks
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 99

[{"id":1,"name":"Flat White","price_halalas":1400},{"id":2,"name":"Cortado","price_halalas":1200}]

$ curl -i localhost:5055/drinks/99
HTTP/1.1 404 NOT FOUND
{"error":"drink not found"}

$ curl -i -X POST localhost:5055/drinks -H 'Content-Type: application/json' \
       -d '{"name":"V60","price_halalas":1800}'
HTTP/1.1 201 CREATED
Location: /drinks/3
{"id":3,"name":"V60","price_halalas":1800}

$ curl -i -X POST localhost:5055/drinks -H 'Content-Type: application/json' -d '{"name":"V60"}'
HTTP/1.1 400 BAD REQUEST
{"error":"name and integer price_halalas are required"}

$ curl -s -o /dev/null -w "%{http_code}\n" -X DELETE localhost:5055/drinks/3
204

الخطوة 4: استهلكه من بايثون

import requests

BASE = "http://localhost:5055"

r = requests.get(f"{BASE}/drinks", timeout=5)
print(r.status_code, r.headers["Content-Type"], r.json()[0])
# 200 application/json {'id': 1, 'name': 'Flat White', 'price_halalas': 1400}

r = requests.get(f"{BASE}/drinks/99", timeout=5)
print(r.status_code, r.json())          # 404 {'error': 'drink not found'}
try:
    r.raise_for_status()
except requests.HTTPError as e:
    print("HTTPError:", e)              # HTTPError: 404 Client Error: NOT FOUND for url: ...

r = requests.post(f"{BASE}/drinks", json={"name": "Mocha", "price_halalas": 1600}, timeout=5)
print(r.status_code, r.headers["Location"], r.json())
# 201 /drinks/3 {'id': 3, 'name': 'Mocha', 'price_halalas': 1600}

الخطوة 5: النسخة العارية بـhttp.server (لترى ما يخفيه Flask)

import json
from http.server import BaseHTTPRequestHandler, HTTPServer

DRINKS = [{"id": 1, "name": "Flat White"}, {"id": 2, "name": "Cortado"}]

class Handler(BaseHTTPRequestHandler):
    def _send(self, status, payload):
        body = json.dumps(payload).encode("utf-8")
        self.send_response(status)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def do_GET(self):
        if self.path == "/drinks":
            self._send(200, DRINKS)
        else:
            self._send(404, {"error": "not found"})

HTTPServer(("127.0.0.1", 5056), Handler).serve_forever()

جرّبناها: curl -i localhost:5056/drinks تعطي HTTP/1.0 200 OK مع Content-Type: application/json; charset=utf-8‏، وأي مسار آخر يعطي 404. لاحظ أنك كتبت بيدك الترميز وطول المحتوى وكل ترويسة، ولا مكان هنا لـPOST إلا بقراءة self.rfile.read(length) بنفسك والتحقق منه يدويًا.

الخطوة 6: احمِ عملية الحذف بتذكرة

import hmac
from functools import wraps
from flask import request, jsonify

API_TOKEN = "..."   # من متغير بيئة في الواقع، لا من الكود

def require_token(view):
    @wraps(view)
    def wrapper(*args, **kwargs):
        scheme, _, token = request.headers.get("Authorization", "").partition(" ")
        if scheme != "Bearer" or not hmac.compare_digest(token, API_TOKEN):
            return jsonify(error="authentication required"), 401, {"WWW-Authenticate": "Bearer"}
        return view(*args, **kwargs)
    return wrapper

@app.delete("/drinks/<int:drink_id>")
@require_token
def delete_drink(drink_id):
    ...

جرّبناه بعميل اختبار Flask: الطلب بلا ترويسة يعطي 401 مع WWW-Authenticate: Bearer‏، وتذكرة خاطئة تعطي 401‏، والتذكرة الصحيحة تعطي 204‏. لاحظ استخدام hmac.compare_digest لمقارنة ثابتة الزمن بدل ==‏.

from werkzeug.security import generate_password_hash, check_password_hash

h = generate_password_hash("correct horse")       # يبدأ بـ scrypt:... ويحمل الملح داخله
check_password_hash(h, "correct horse")            # True
check_password_hash(h, "nope")                     # False

الخطوة 7: شاهد ما بداخل JWT (لتفهم لماذا لا تضع فيه أسرارًا)

import base64, hashlib, hmac, json

def b64(b): return base64.urlsafe_b64encode(b).rstrip(b"=").decode()

header  = b64(json.dumps({"alg": "HS256", "typ": "JWT"}, separators=(",", ":")).encode())
payload = b64(json.dumps({"sub": "noura", "role": "barista", "exp": 1790000000}, separators=(",", ":")).encode())
sig = b64(hmac.new(b"demo-secret", f"{header}.{payload}".encode(), hashlib.sha256).digest())
token = f"{header}.{payload}.{sig}"

print(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
# b'{"sub":"noura","role":"barista","exp":1790000000}'    <- بلا أي مفتاح!

الخطوة 8: وثّق العقد بـOpenAPI

ملف YAML واحد (فحصنا صحة بنيته بقارئ YAML) يصف الواجهة التي بنيناها. ألصقه في Swagger Editor لترى صفحة التوثيق التفاعلية:

openapi: 3.0.3
info:
  title: Coffee Menu API
  version: "1.0.0"
servers:
  - url: http://localhost:5055
paths:
  /drinks:
    get:
      summary: List all drinks
      responses:
        "200":
          description: A JSON array of drinks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
    post:
      summary: Create a drink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewDrink"
      responses:
        "201":
          description: Created
          headers:
            Location:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Drink"
        "400":
          description: Invalid input
  /drinks/{drinkId}:
    parameters:
      - name: drinkId
        in: path
        required: true
        schema:
          type: integer
    get:
      summary: Get one drink
      responses:
        "200":
          description: The drink
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Drink"
        "404":
          description: Not found
    delete:
      summary: Delete a drink
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Deleted
        "401":
          description: Missing or invalid token
        "404":
          description: Not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    NewDrink:
      type: object
      required: [name, price_halalas]
      properties:
        name:
          type: string
        price_halalas:
          type: integer
          minimum: 0
    Drink:
      allOf:
        - $ref: "#/components/schemas/NewDrink"
        - type: object
          properties:
            id:
              type: integer

خرافة مقابل حقيقة

أين تُستخدم الواجهات فعليًا؟

جرّب بنفسك

بطاقات مراجعة سريعة

اختبر فهمك