4.4إنشاء واجهة REST (API REST) ومصادقة JWT
الأساسي في 30 ثانية
- REST = موارد + طرق :
GET /api/produits(عرض القائمة، 200) وPOST(إنشاء، 201) وPUT(تعديل) وDELETE(حذف) — JSON في كل مكان. - JWT = رمز موقع محمول ذاتيا : يُصدر عند الاتصال، ويُرجع في
Authorization: Bearer …، ويُتحقق منه دون جلسة — مناسب للواجهة المنفصلة والهاتف. - منعكس رياد : سر JWT في متغير بيئة (
.env، وليس في الكود أبدا) و HTTPS ضروري وتحقق + أخطاء JSON نظيفة.
حالة مصغرة متواصلة — رياد يفتح فهرسه واجهة
يريد متجر رياد تطبيق هاتف في قسنطينة : يجب أن يخرج فهرسه بـ JSON، لا بـ HTML. يصمم رياد نقاط النهاية (GET عرض القائمة/قراءة و POST إنشاء في 201 و PUT و DELETE)، ويرجع JSON بالرموز الصحيحة، ثم يؤمن : عند الاتصال يصدر JWT موقعا سره يعيش في .env، وكل طلب هاتف يرجعه في ترويسة Authorization. وعندما يغيب الرمز أو يُزوَّر، تجيب الواجهة 401 دون كشف البيانات. رابع محطة في الخيط الرابط : الخلفية نفسها تخدم الموقع والهاتف.
تتمة حالة 4.1-4.3 — يفصل رياد خلفيته عن عملائه.
1. واجهة REST (API REST)
تعرض الواجهة (API) بيانات (JSON) لبرامج أخرى : واجهة جافاسكريبت منفصلة (React و Vue) وتطبيق هاتف وخدمات أخرى. وأسلوب REST : موارد عبر روابط واضحة، تُعالَج بـ طرق HTTP حسب دلالتها — GET /api/produits (عرض القائمة) وGET /api/produits/{id} (قراءة) وPOST /api/produits (إنشاء، 201) وPUT/PATCH /api/produits/{id} (تعديل) وDELETE /api/produits/{id} (حذف) — وردود JSON بالرموز الصحيحة (200 و201 و400 و401 و404). في PHP يمكن الترقيع باليد (موجّه وjson_encode وترويسات ورموز) لكن في الحقيقي نستعمل أدوات الواجهة في أطر العمل (توجيه الواجهة والتسلسل والتحقق).
2. المصادقة بالرموز (JWT)
بروتوكول HTTP دون حالة والواجهة تخدم عملاء متنوعين (لا كوكيز متصفح مضمونة) : نتوثق بـ رموز. وJWT (رمز الوب JSON) (JSON Web Token) : بعد اتصال ناجح، يصدر الخادم رمزا موقعا تشفيريا (يثبت الهوية دون قابلية تزوير) ؛ ويخزنه العميل ويرجعه مع كل طلب (Authorization: Bearer <jeton>) ؛ ويتحقق الخادم من التوقيع — دون تخزين جلسة، ومن هنا «محمول ذاتيا». مثالي للواجهة المنفصلة والهاتف والخوادم المتعددة. وتقدم أطر العمل أنظمة مصادقة واجهة متينة (لا ترقيع لتشفيركم في الإنتاج).
أمن الواجهة غير قابل للتفاوض : رموز آمنة لمدة قصيرة وHTTPS ضروري (الرموز تسافر) وتحقق من المدخلات وتخويل (الحقوق، لا الهوية فقط) وأخطاء JSON متسقة (رموز + رسائل، دون تسربات) وتحديد المعدل. الواجهة المصممة جيدا متوقعة واحترافية وآمنة — مُسلَّمة بنى خلفية + واجهة/هاتف مفصولة.
الـ 200 الشامل (مشهد لا يُعاد)
العبرة : 201 عند الإنشاء، و404 عند الغياب، و400 عند عدم الصلاحية — يقول JSON ماذا، ويقول الرمز كيف.
🔎 مثال ملموس — 🔎 مثال ملموس — نقاط نهاية فهرس رياد
الجدول الذي يعرضه رياد فوق شاشته :
GET /api/produits ← عرض القائمة (200)
GET /api/produits/{id} ← قراءة (200، 404 عند الغياب)
POST /api/produits ← إنشاء (201، 400 عند عدم الصلاحية)
PUT /api/produits/{id} ← تعديل (200، 404 عند الغياب)
DELETE /api/produits/{id} ← حذف (204)
المصادقة ← Authorization: Bearer (401 عند الغياب/عدم الصلاحية) القراءة : خمسة أسطر وخمسة أزواج طريقة + رابط + رمز.
الدرس : الفعل يأتي من الطريقة، وإثبات الهوية من الرمز.
مفردات القسم
- واجهة REST (API REST)
- واجهة تعرض بيانات (JSON) لبرامج أخرى (واجهة وهاتف وخدمات) ؛ وموارد عبر روابط وطرق HTTP دلالية ورموز حالة.
مثال بسيط: فهرس JSON خاص برياد يخدم الموقع وتطبيق الهاتف.
ما ليس كذلك: صفحة HTML مولدة جهة الخادم فقط.
رد فعل: مورد + طريقة + رمز منتظر لكل نقطة نهاية.
- الموارد والطرق (واجهة)
- GET عرض القائمة/قراءة و POST إنشاء (201) و PUT/PATCH تعديل و DELETE حذف ؛ و JSON بالرموز الصحيحة (200 و201 و400 و401 و404…).
مثال بسيط: ينشئ رياد في POST ← 201، ويقرأ غائبا ← 404.
ما ليس كذلك: كل شيء في POST مع 200 حتى عند الخطأ.
رد فعل: لا 200 أبدا لخطأ، ولا فعل أبدا في الرابط.
- المصادقة بالرموز
- للواجهات (دون حالة وعملاء متنوعون) : بعد الاتصال، رمز يُرجع مع كل طلب (Authorization) ويتحقق منه الخادم.
مثال بسيط: هاتف رياد يرجع رمزه مع كل نداء فهرس.
ما ليس كذلك: جلسة كوكيز مفترضة متاحة في كل مكان.
رد فعل: كل مسار حساس يطلب الرمز ويتحقق منه.
- JWT (رمز الوب JSON)
- رمز موقع تشفيريا ومحمول ذاتيا (دون تخزين خادم)، يُرجع مع كل طلب ويُتحقق منه. مناسب للواجهة المنفصلة والهاتف.
مثال بسيط: يصدر رياد JWT عند الاتصال ويتحقق من توقيعه بعدها.
ما ليس كذلك: معرف متوقع يُمرَّر في سلسلة استعلام.
رد فعل: توقيع متحقق منه ومدة قصيرة ولا حساس فيه.
- أمن الواجهة
- رموز آمنة و HTTPS ضروري وتحقق من المدخلات وتخويل (حقوق) وأخطاء JSON نظيفة وتحديد معدل.
مثال بسيط: يجمع رياد HTTPS + تحقق + 401/403 نظيفة + حد معدل.
ما ليس كذلك: واجهة دون HTTPS تقبل كل شيء وتجيب 200.
رد فعل: الرمز يسافر : يجب أن يسافر مشفرا وينتهي سريعا.
في التطبيق — عمليا — عرض البيانات عبر واجهة REST
- صمموا نقاط نهاية مورد حسب REST : GET عرض القائمة/قراءة و POST إنشاء (201) و PUT تعديل و DELETE حذف — وردود JSON.
- أرجعوا JSON بالرموز الصحيحة (json_encode + ترويسات باليد، أو أدوات واجهة إطار عمل).
- أمنوا بـ JWT : رمز موقع مُصدَر عند الاتصال (السر في .env)، متحقق منه مع كل طلب (Authorization).
- أضيفوا HTTPS وتحققا وتخويلا وأخطاء JSON متسقة وتحديد معدل.
نص جاهز للقول — عرض واجهته لزبون الهاتف (30 ثانية)
« هذا رياد : تعرض واجهتنا الفهرس بـ JSON — GET للقراءة و POST في 201 للإنشاء و PUT و DELETE، بالرموز الصحيحة. يصدر الاتصال JWT موقعا سره يعيش في .env، وكل طلب يرسله في Authorization، وكل شيء يسافر في HTTPS. »
يُقال في عرض ؛ واعرضوا جدول نقاط النهاية ونداء برمز.
نموذج نسخ-لصق — واجهة PHP + JWT عبر البيئة (كود مُختبَر)
'Configuration serveur manquante']); exit; }
header('Content-Type: application/json');
$methode = $_SERVER['REQUEST_METHOD'];
$chemin = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
// الاتصال : يتحقق (تجزئة في الحقيقي)، ويصدر JWT قصيرا
if ($methode === 'POST' && $chemin === '/api/connexion') {
$corps = json_decode(file_get_contents('php://input'), true) ?? [];
if (empty($corps['email']) || empty($corps['motDePasse'])) {
http_response_code(400); echo json_encode(['erreur' => 'Email et mot de passe requis']); exit;
}
$jeton = JWT::encode(['sub' => $corps['email'], 'iat' => time(), 'exp' => time() + 3600], $secret, 'HS256');
echo json_encode(['jeton' => $jeton]); exit;
}
// مسار محمي : يتحقق من JWT (401 عند الغياب/عدم الصلاحية)
if ($methode === 'GET' && $chemin === '/api/produits') {
$entete = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
if (!str_starts_with($entete, 'Bearer ')) { http_response_code(401); echo json_encode(['erreur' => 'Jeton manquant']); exit; }
try {
JWT::decode(substr($entete, 7), new Key($secret, 'HS256'));
} catch (Exception $e) { http_response_code(401); echo json_encode(['erreur' => 'Jeton invalide']); exit; }
echo json_encode([['nom' => 'Couscoussier', 'prix' => 2500]]); exit;
}
http_response_code(404); echo json_encode(['erreur' => 'Introuvable']);
نموذج محلي
نقاط نهاية JSON باليد (موجّه + json_encode) : اتفاقيات REST منذ البدء، ولا تكلف شيئا.
تطبيق حقيقي
مثل رياد : أدوات واجهة إطار العمل و JWT عبر .env و HTTPS وتحقق وتحديد معدل.
واجهة متعددة العملاء
خلفية واحدة للوب + الهاتف : صدروا (/api/v1/) لتتطوروا دون كسر.
بيانات حساسة
مدة رمز قصيرة وإبطال متوقع ولا حساس في الحمولة — وتدقيق قبل الإنتاج.
.env خارج Git)، وليس في الكود أبدا ؛ وHTTPS إجباري (الرموز تسافر مكشوفة وإلا) ؛ ومدة قصيرة وتحقق منهجي. أمثلة ببيانات وهمية فقط — لا سر حقيقي. محتوى تعليمي، وليس تدقيق أمن.✓ ممارسات جيدة
- التصميم بموارد + طرق + رموز صحيحة.
- المصادقة بـ JWT متحقق منه مع كل طلب.
- فرض HTTPS وتحقق وأخطاء JSON نظيفة.
✗ أخطاء شائعة
- إرجاع كل شيء في 200 حتى عند الخطأ.
- عرض واجهة دون HTTPS.
- ترقيع تشفير JWT خاص في الإنتاج.
النقاط الأساسية
- واجهة REST = بيانات JSON للواجهة/الهاتف/الخدمات : موارد عبر روابط وطرق دلالية ورموز صحيحة.
- باليد (موجّه و json_encode) أو عبر إطار عمل (توجيه واجهة وتسلسل وتحقق).
- JWT : رمز موقع محمول ذاتيا (Authorization: Bearer)، متحقق منه دون جلسة — مناسب للعملاء المتنوعين.
- الأمن : السر في .env و HTTPS وتحقق وتخويل وأخطاء نظيفة وتحديد معدل.
تحدي 48 ساعة — طبّق غدا
اعرضوا موردا واحدا بـ JSON (5 نقاط نهاية ورموز صحيحة) + اتصال JWT (السر في .env) وتحققوا من 401 دون رمز.
- أستطيع ذكر نقاط النهاية الخمس ورموزها.
- أعرف شرح JWT مقابل الجلسات.
- عندي مسار محمي واحد مُختبَر مع رمز ودونه.
أسئلة شائعة
لماذا نبني واجهة بدل موقع يولد HTML ؟
عندما لا يكون المستهلك متصفحا وحده : تطبيق واجهة منفصلة (React/Vue/Angular و SPA تفاعلية) وتطبيق هاتف (لا يستهلك إلا JSON) وعملاء متعددون (وب + هاتف + شركاء على خلفية واحدة معاد استعمالها) وبنى خدمات/خدمات صغرى. وإلا، يبقى الموقع الكلاسيكي (HTML الخادم) أبسط. يختار رياد الواجهة حالما يدخل هاتف أو واجهة مفصولة.
ما هو JWT — ولماذا رموز بدل جلسات للواجهات ؟
الجلسات : حالة جهة الخادم + كوكيز متصفح — جيدة لموقع كلاسيكي، لكنها مرتبطة بالمتصفح ومعقدة على مقياس خوادم متعددة. JWT : رمز موقع مُصدَر عند الاتصال ومخزن جهة العميل ومُرجع في Authorization ومتحقق منه بالتوقيع — دون حالة خادم، ومناسب للعملاء المتنوعين (هاتف وخدمات) والانتقال للمقياس. انتباهات : مفتاح محمي (ليس في الكود أبدا) ومدة قصيرة/تحديث ولا حساس في الحمولة و HTTPS.
لماذا رموز (JWT) بدل جلسات لواجهة ؟