دروس السلسلة: Elementor 4 و Atomic Editor · تأمين ووردبريس 2026 · تحسين أداء ووردبريس 2026
لماذا تُعدّ REST API نقطة تحوّل في عالم ووردبريس
عند الحديث عن تطوير المواقع الحديثة، لم تعد ووردبريس مجرد منصة لإنشاء المدونات؛ بل أصبحت نظامًا كاملاً لإدارة المحتوى يقف خلف ما يقارب ثلث المواقع حول العالم. ومع إصدار ووردبريس 6.9 في مايو 2026، باتت واجهة REST API مكوّنًا أساسيًا يفتح الباب أمام تطبيقات الهاتف، ومواقع Headless مبنية على Next.js أو Nuxt، وأدوات أتمتة سير العمل، وحتى لوحات تحكّم مخصّصة بعيدًا عن لوحة wp-admin التقليدية.
يستهدف هذا الدرس كل مطوّر يريد أن يفهم كيف تتحدّث ووردبريس مع العالم الخارجي بلغة JSON، وكيف يستطيع المرور من قارئ سلبي للوثائق إلى بانٍ نشط لنقاط نهاية (endpoints) مخصّصة، آمنة وسريعة. سنشرح كل خطوة بالتفصيل: من الاستدعاء الأول إلى المصادقة عبر Application Passwords، مرورًا بإنشاء endpoint خاص بقواعد عملك، وصولًا إلى التحكّم في الأداء وتقليل أخطاء الإنتاج.
الخطوة 1: التحقّق من تفعيل REST API على موقعك
قبل البدء بأي كود، يجب التأكد أن واجهة REST API تعمل وأن المخدّم لا يحجبها. تأتي الواجهة مفعّلة افتراضيًا منذ ووردبريس 4.7، لكن بعض إضافات الأمان مثل Kadence Security (المعروف سابقًا باسم Solid Security) أو إعدادات .htaccess صارمة قد تحجب المسار /wp-json/.
الاختبار الأبسط هو فتح متصفّحك على عنوان موقعك متبوعًا بـ /wp-json/wp/v2/posts. إن ظهرت لك مصفوفة JSON تحتوي على آخر المقالات، فالواجهة تعمل. أمّا إذا واجهت خطأ 403 أو 404، فجرّب المسار البديل الذي يمرّ مباشرةً عبر index.php:
curl -i "https://example.com/index.php?rest_route=/wp/v2/posts"إذا أعاد المخدّم ترويسة HTTP/1.1 200 OK ومحتوى JSON، فأنت جاهز. هذا المسار البديل مفيد جدًا حين تحجب قواعد التصلّب (Hardening) في .htaccess كل ما يبدأ بـ /wp-json/. علامة النجاح هنا: قراءة قائمة المقالات في طرفية الـ curl دون الحاجة لأي مفتاح.
الخطوة 2: فهم بنية نقاط النهاية الأساسية
تنظّم ووردبريس نقاط النهاية ضمن مساحات أسماء (namespaces). المساحة الأصلية هي wp/v2، وتضمّ كل ما يخصّ المحتوى: المقالات، الصفحات، الوسائط، المستخدمين، التصنيفات، الوسوم، التعليقات، والقوائم. كل مورد له ثلاث صيغ: GET للقراءة، POST للإنشاء، وPUT/PATCH للتعديل، وDELETE للحذف.
على سبيل المثال، لجلب آخر عشرة مقالات منشورة مع تضمين بيانات المؤلف والصور المميّزة، تستخدم المعاملات التالية:
GET /wp-json/wp/v2/posts?per_page=10&_embed=author,wp:featuredmedia&orderby=date&order=descالمعامل _embed هو مفتاح ذهبي: بدلاً من إجراء ثلاثة استدعاءات (مقال، ثم مؤلف، ثم صورة)، يدمج ووردبريس كل البيانات المرتبطة في استجابة واحدة. ميزته أنه يقلّل عدد الطلبات على المخدّم بنسبة قد تصل إلى 70٪، وهذا أمر حاسم على مواقع Headless.
لاكتشاف بنية أي endpoint، استخدم الاستدعاء التفسيري:
curl "https://example.com/wp-json/wp/v2/posts?context=help"سيعيد لك ووردبريس مخطّط (schema) كامل: الحقول المتاحة، نوع كل حقل، القيم المسموح بها، والصلاحيات المطلوبة. هذه آلية أساسية للتعامل مع REST API بأمان دون تخمين.
الخطوة 3: المصادقة عبر Application Passwords
إنشاء أو تعديل المحتوى يتطلّب توثيقًا. منذ ووردبريس 5.6 (وحتى الإصدار الحالي 6.9.4)، يوجد نظام Application Passwords مدمج رسميًا، وهو الطريقة الأكثر أمانًا للاتصال بالموقع من تطبيق خارجي. لإنشاء كلمة مرور تطبيق، توجّه إلى لوحة التحكم: المستخدمون > ملفك الشخصي، انزل إلى قسم « Application Passwords »، أدخل اسمًا مميّزًا مثل « تطبيق-الموبايل-2026″، ثم اضغط « إضافة ».
ستُظهر لك ووردبريس سلسلة من 24 محرفًا مقسّمة إلى ست مجموعات. هذه الكلمة لا تظهر مرّة ثانية، فاحفظها فورًا في مدير كلمات المرور. الاستدعاء التالي يستخدم Basic Auth لإنشاء مقالة جديدة:
curl -X POST "https://example.com/wp-json/wp/v2/posts" \
-u "merass:xxxx xxxx xxxx xxxx xxxx xxxx" \
-H "Content-Type: application/json" \
-d '{"title":"مقال من API","content":"محتوى تجريبي","status":"publish"}'إذا أعاد المخدّم رمز 201 ومعرّف المقال، فالعملية نجحت. علامة النجاح: ظهور المقال فورًا في قائمة المقالات داخل لوحة wp-admin. الميزة الجوهرية لـ Application Passwords أنها قابلة للإبطال فوريًا دون الحاجة لتغيير كلمة مرور حساب المسؤول الرئيسي.
الخطوة 4: استخدام JWT للتطبيقات الحديثة
على الرغم من بساطة Application Passwords، فإن البنى الحديثة المبنية على React Native أو Flutter تفضّل JSON Web Tokens (JWT) لأنها أخفّ في النقل وأكثر تكاملاً مع وسائط التحقّق المعمول بها في الواجهات الأمامية. الإضافة المرجعية هي JWT Authentication for WP REST API، وهي مجانية ومتوفّرة في مستودع ووردبريس الرسمي.
بعد التثبيت والتفعيل، أضف هذين السطرين إلى ملف wp-config.php فوق سطر /* That's all, stop editing! */:
define('JWT_AUTH_SECRET_KEY', 'مفتاح-سري-طويل-وعشوائي');
define('JWT_AUTH_CORS_ENABLE', true);لتوليد سلسلة سرّية قويّة، استخدم خدمة https://api.wordpress.org/secret-key/1.1/salt/ وانسخ أحد المفاتيح. الاستدعاء التالي يولّد رمز JWT صالحًا لمدة 7 أيام افتراضيًا:
curl -X POST "https://example.com/wp-json/jwt-auth/v1/token" \
-H "Content-Type: application/json" \
-d '{"username":"merass","password":"كلمة-المرور-الأصلية"}'تعيد الاستجابة كائنًا يحتوي على حقل token. تخزّن هذه القيمة في التطبيق ثم تمرّرها في ترويسة Authorization: Bearer <token> مع كل طلب لاحق. علامة النجاح: تمكّنك من جلب /wp/v2/users/me وعرض بيانات حسابك دون إعادة إرسال كلمة المرور.
الخطوة 5: بناء endpoint مخصّص لقاعدة عملك
قوّة REST API الحقيقية تظهر حين تنشئ نقاط نهاية تعكس منطق عملك الخاص. لنفترض أنك تدير موقعًا تعليميًا وتريد endpoint يعيد ملخّصًا للدورات النشطة مع عدد المسجّلين في كل دورة. أضف الكود التالي إلى ملف functions.php في القالب الفرعي (child theme):
add_action('rest_api_init', function () {
register_rest_route('itskills/v1', '/courses/stats', [
'methods' => 'GET',
'callback' => 'itskills_courses_stats',
'permission_callback' => function () {
return current_user_can('edit_posts');
},
]);
});
function itskills_courses_stats() {
$courses = get_posts([
'post_type' => 'course',
'numberposts' => -1,
'post_status' => 'publish',
]);
$data = [];
foreach ($courses as $c) {
$data[] = [
'id' => $c->ID,
'title' => $c->post_title,
'students' => (int) get_post_meta($c->ID, '_students_count', true),
];
}
return rest_ensure_response($data);
}بعد حفظ الملف، اختبر النتيجة بالاستدعاء التالي وأنت متّصل بحسابك:
curl "https://example.com/wp-json/itskills/v1/courses/stats" \
-u "merass:xxxx xxxx xxxx xxxx xxxx xxxx"علامة النجاح: ستحصل على مصفوفة JSON تحتوي على عناوين الدورات مع أعداد الطلاب. لاحظ أن permission_callback ليست اختيارية: تركها مفتوحة (__return_true) يُعدّ ثغرة أمنية، وقد رفض ووردبريس منذ الإصدار 5.5 تسجيل أي endpoint بلا فحص صلاحيات صريح.
الخطوة 6: ضبط CORS للتطبيقات الأمامية
عندما يستهلك تطبيق Next.js مستضاف على نطاق مختلف بيانات ووردبريس، يصطدم المتصفح بسياسة Same-Origin. الحلّ هو إضافة ترويسات CORS عبر فلتر rest_pre_serve_request:
add_filter('rest_pre_serve_request', function ($served, $result, $request) {
$allowed = ['https://app.example.com', 'https://admin.example.com'];
$origin = get_http_origin();
if ($origin && in_array($origin, $allowed, true)) {
header('Access-Control-Allow-Origin: ' . esc_url_raw($origin));
header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
header('Access-Control-Allow-Headers: Authorization, Content-Type, X-WP-Nonce');
header('Access-Control-Allow-Credentials: true');
}
return $served;
}, 10, 3);لاحظ أنّ القائمة $allowed صريحة وليست *. السماح للجميع يفتح بابًا أمام هجمات CSRF متقدّمة. علامة النجاح: تختفي رسالة « blocked by CORS policy » من وحدة تحكم المتصفّح في تطبيقك الأمامي.
الخطوة 7: تقييد المعدّل (Rate Limiting) وحماية الـ API
لا تتضمّن ووردبريس rate limiting افتراضيًا، وهذا يجعل endpoints مثل /users هدفًا سهلاً لمحاولات تعداد الحسابات. الحلّ العملي هو إضافة طبقة بسيطة بناءً على transients:
add_filter('rest_authentication_errors', function ($result) {
if (!empty($result)) return $result;
$ip = $_SERVER['REMOTE_ADDR'] ?? 'unknown';
$key = 'rest_rate_' . md5($ip);
$count = (int) get_transient($key);
if ($count >= 60) {
return new WP_Error('rate_limited', 'تجاوزت الحد المسموح', ['status' => 429]);
}
set_transient($key, $count + 1, MINUTE_IN_SECONDS);
return $result;
});هذا الكود يسمح بستين طلبًا في الدقيقة من نفس عنوان IP. للمواقع التي تتلقّى حركة مرور عالية، استبدل التخزين بـ Redis عبر إضافة Redis Object Cache لتفادي الضغط على قاعدة البيانات. علامة النجاح: إرسال 70 طلبًا متتاليًا يعيد رمز 429 من الطلب الحادي والستين.
الخطوة 8: قياس الأداء والتنقيح في الإنتاج
قبل نشر أي تطبيق يعتمد على REST API، فعّل سجل الطلبات. الإضافة Query Monitor هي السكين السويسري لتنقيح الـ API: تعرض كل استعلام SQL ينفّذه كل endpoint، زمن المعالجة، استهلاك الذاكرة، وأي تحذيرات PHP. على ووردبريس 6.9 مع PHP 8.3، يعطي القياس الواقعي على endpoint مخصّص جيّد البناء زمن استجابة بين 80 و120 مللي ثانية، ويرتفع إلى 600 مللي ثانية إذا أهملت فهرسة meta_key في قاعدة البيانات.
للأداء على نطاق واسع، ضع طبقة تخزين مؤقّت أمام REST API. إضافة WP REST Cache (مفتوحة المصدر) أو WP Rocket (تجاريّة) تحفظ استجابات GET في ذاكرة الخادم لمدة قابلة للتعديل. اختبار حقيقي على استضافة Hostinger Business يُظهر انخفاض زمن الاستجابة من 220 مللي ثانية إلى 35 مللي ثانية بعد تفعيل التخزين المؤقّت لمدّة 5 دقائق.
الخطوة 9: استهلاك REST API من تطبيق JavaScript حديث
لإغلاق الدائرة، إليك مثالًا عمليًا بـ fetch الأصلي من جانب المتصفّح، يجلب آخر خمس مقالات ويعرضها بطاقات:
async function loadLatestPosts() {
const url = 'https://example.com/wp-json/wp/v2/posts?per_page=5&_embed=wp:featuredmedia';
const res = await fetch(url);
const posts = await res.json();
const container = document.getElementById('posts');
container.innerHTML = posts.map(p => `
<article>
<h3>${p.title.rendered}</h3>
<p>${p.excerpt.rendered}</p>
</article>
`).join('');
}
loadLatestPosts();هذا النموذج يعمل من نطاق مختلف بشرط ضبط CORS كما في الخطوة 6. علامة النجاح: ظهور البطاقات الخمس فور تحميل الصفحة دون أي تحذيرات في وحدة التحكّم.
الأخطاء الشائعة وحلولها
الخطأ الأكثر تكرارًا هو رمز 401 رغم تمرير اسم المستخدم وكلمة المرور. السبب 95٪ من الأوقات: مخدّم Apache يحذف ترويسة Authorization. الحلّ إضافة هذا السطر في .htaccess:
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [E=HTTP_AUTHORIZATION:%1]الخطأ الثاني هو 403 على endpoint عام مثل /wp/v2/users. هذا سلوك متعمّد: ووردبريس يخفي قائمة المستخدمين عن غير المسجّلين منذ 4.7.1. لكشفها للمحرّرين فقط، أضف معامل ?context=edit مع توثيق صالح.
الخطأ الثالث، وغالبًا ما يربك مطوّري Headless في المغرب أو منطقة الخليج، هو 502 Bad Gateway تحت ضغط. السبب الأساسي ضعف الذاكرة في PHP-FPM. الحلّ المباشر: زيادة memory_limit في php.ini إلى 256M مع max_execution_time إلى 60.
خاتمة عمليّة
تحوّلت ووردبريس REST API من ميزة جانبية إلى محور التطوير الحديث على المنصّة. سواء كنت تبني واجهة موبايل لمشروع تجارة إلكترونية في الرياض، أو تطبيق ويب Headless لمؤسسة تعليمية في القاهرة، أو لوحة تحكّم B2B لشركة لوجستيك في الدار البيضاء، فإن إتقان الخطوات التسع السابقة يضمن لك بنية سريعة وآمنة وقابلة للتوسعة. ابدأ بنقطة نهاية واحدة بسيطة، أضف إليها المصادقة، ثم وسّع تدريجيًا حتى تبني نظامك الكامل.