إنشاء نقاط النهاية المخصصة في WordPress REST API: قراءة عامة بعقد محدود وتأمين صارم

يا أهلاً بيك يا صديقي المطور! كتير مننا لما بيحتاج يربط تطبيق موبايل أو واجهة فرونت إند مبنية بـ Next.js أو Vue بموقع ووردبريس عشان يعرض بيانات عامة (زي أسعار الذهب، أحدث المقالات المختارة، حالة الطقس، أو إحصائيات المنصة)، بيستسهل ويفتح نقطة نهاية عامة (Public Read Endpoint) بـ 'permission_callback' => '__return_true'، ويرجع مصفوفة كاملة مسحوبة بـ SELECT * من قاعدة البيانات! الكارثة هنا إنك بدون ما تقصد بتكون فتحت تسريب أمني فادح لبيانات موقعك الحساسة، وخليت سيرفرك عرضة لهجمات الحرمان من الخدمة (DDoS) وتفريغ الباندويث في ثواني معدودة. في المقال ده، هنتعلم إزاي نبني Custom REST Endpoint للقراءة العامة باحترافية شديدة، ولكن بعقد محدود ومحدد بدقة (Limited Schema Contract)، مع دعم كامل للـ Edge Caching وترويسات الـ ETag لتقليل الحمل على السيرفر بنسبة 99%.

فلسفة القراءة العامة بعقد محدود (The Limited Schema Pattern)

في أمن المعلومات وهندسة الـ APIs، في قاعدة ذهبية اسمها “مبدأ الحد الأدنى من الإفصاح” (Principle of Least Privilege Data Exposure). المبدأ ده بيقول: لو تطبيق الموبايل محتاج يعرض اسم المنتج وسعره فقط، إياك ترجع له كائن الـ Post كاملاً! ليه بقى؟

• منع تسريب البيانات الحساسة (Information Disclosure): كائن المنشور الافتراضي في ووردبريس أو حقول الـ Postmeta ممكن تحتوي على بيانات داخلية مش المفروض أي حد يشوفها؛ زي إيميلات المحررين، مسارات السيرفر الفيزيائية، إعدادات الـ SEO الداخلية، أو حتى ملاحظات الإدارة الخاصة.
• توفير الباندويث وسرعة التحميل (Bandwidth Optimization): كائن المنشور الكامل في الـ REST API الافتراضي بيوصل حجمه أحياناً لـ 20 كيلوبايت أو أكثر بسبب كثرة الحقول المرجعة وروابط الـ HATEOAS. لو النقطة الطرفية دي بيطلبها 50,000 مستخدم في الساعة، أنت بتستهلك جيجابايتات من الباندويث على الفاضي! في حين إن العقد المحدود هيرجع 300 بايت فقط!
• حماية قاعدة البيانات وتفادي الـ Heavy Joins: العقد المحدود بيخلي استعلام SQL بتاعك يجلب فقط الأعمدة اللي أنت محتاجها بـ SELECT id, title, price بدل ما يرهق محرك MySQL بجلب نصوص المقالات الضخمة والـ Postmeta المعقدة.

هندسة التخزين المؤقت وحماية النقطة العامة من الانهيار (Edge Caching & ETag)

بما إن النقطة دي “قراءة عامة” (Public GET)، يعني كل المستخدمين في العالم هيشوفوا نفس المحتوى تقريباً، يبقى من قمة الغباء الهندسي إن كل ريكوست يروح يفتح ووردبريس وقاعدة البيانات! المعادلة الصح لنقطة قراءة عامة ناجحة بتعتمد على ركنين:

1. ترويسات التحكم في الكاش (HTTP Cache-Control Headers)

بنحقن ترويسات بتفهم خوادم الـ CDN (زي Cloudflare) والمتصفحات إن الرد ده صالح للتخزين:

Cache-Control: public, max-age=300, s-maxage=3600, stale-while-revalidate=60

الترويسة دي معناها: المتصفح يخزن الرد عنده لمدة 5 دقائق (max-age=300)، وشبكة الـ CDN تخزنه على حافة الشبكة لمدة ساعة كاملة (s-maxage=3600). بكده 99.9% من الريكوستات هيتم خدمتها من سيرفرات Cloudflare في أقل من 15ms بدون ما تلمس سيرفر الووردبريس بتاعك أصلاً!

2. الاستعلامات الشرطية عبر الـ ETag و If-None-Match

بنحسب التجزئة الرياضية (Hash) للبيانات المرجعة، ونرسلها في ترويسة ETag: "abc123hash". العميل في الطلب التالي بيبعت الترويسة دي في If-None-Match. لو البيانات متعدلتش، السيرفر بيرد فوراً بكود 304 Not Modified بدون إرسال الـ Body، وده بيوفر استهلاك باقة الإنترنت لمستخدمي الهواتف الذكية.

مقارنة معمارية: نقاط القراءة المفتوحة العشوائية مقابل القراءة بعقد محدود

تطبيق برودكشن متكامل: بناء نقطة قراءة عامة للأسعار والأسهم بعقد محدود وكاش ذكي

الكود ده بيطبق أفضل الممارسات الهندسية لبناء Custom REST Endpoint عامة لعرض مؤشرات الأسعار اللحظية (Market Ticker Endpoint) مع تحديد سقف للنتائج، وحساب الـ ETag، وتطبيق كاش الذاكرة (Transient API):

<?php
/**
 * نقطة نهاية مخصصة للقراءة العامة بعقد محدود وتخزين مؤقت فائق السرعة
 * Author: Mohamed Abozaid
 * Route: GET /wp-json/market/v1/ticker
 */

if (!defined('ABSPATH')) {
    exit;
}

class Enterprise_Public_Ticker_Endpoint {

    public const NAMESPACE = 'market/v1';
    public const ROUTE     = '/ticker';
    public const CACHE_KEY = 'az_market_ticker_cache';
    public const CACHE_TTL = 300; // 5 دقائق

    public static function init(): void {
        add_action('rest_api_init', [__CLASS__, 'register_endpoint']);
    }

    public static function register_endpoint(): void {
        register_rest_route(
            self::NAMESPACE,
            self::ROUTE,
            [
                'methods'             => WP_REST_Server::READABLE, // GET
                'callback'            => [__CLASS__, 'handle_request'],
                'permission_callback' => '__return_true', // قراءة عامة مسموحة للجميع
                'args'                => self::get_endpoint_arguments(),
                'schema'              => [__CLASS__, 'get_endpoint_schema'],
            ]
        );
    }

    /**
     * تعريف مواصفات المعاملات المقبولة مع قيود صارمة للحماية
     */
    public static function get_endpoint_arguments(): array {
        return [
            'currency' => [
                'description'       => __('رمز العملة المطلوب عرض المؤشرات لها (EGP, USD, SAR).', 'text-domain'),
                'type'              => 'string',
                'default'           => 'EGP',
                'enum'              => ['EGP', 'USD', 'SAR', 'AED'],
                'sanitize_callback' => 'sanitize_text_field',
                'validate_callback' => function($param) {
                    return in_array(strtoupper($param), ['EGP', 'USD', 'SAR', 'AED'], true);
                },
            ],
            'limit' => [
                'description'       => __('الحد الأقصى لعدد العناصر (محدد بسقف أقصى 50 لمنع الإغراق).', 'text-domain'),
                'type'              => 'integer',
                'default'           => 10,
                'minimum'           => 1,
                'maximum'           => 50, // حماية السيرفر من طلب آلاف السجلات
                'sanitize_callback' => 'absint',
            ],
        ];
    }

    /**
     * معالج الطلب مع تطبيق الـ Transient Cache والـ ETag
     */
    public static function handle_request(WP_REST_Request $request): WP_REST_Response {
        $currency = strtoupper($request->get_param('currency'));
        $limit    = (int) $request->get_param('limit');

        $cache_key = sprintf('%s_%s_%d', self::CACHE_KEY, $currency, $limit);

        // 1. محاولة جلب البيانات من كاش الذاكرة السريع
        $data = get_transient($cache_key);

        if ($data === false) {
            // استعلام قاعدة البيانات بعقد محدود جداً (Only Selected Fields)
            $data = self::query_market_data($currency, $limit);

            // حفظ البيانات في الكاش لمدة 5 دقائق
            set_transient($cache_key, $data, self::CACHE_TTL);
        }

        // 2. حساب البصمة الرقمية للبيانات (ETag Hash)
        $etag = sprintf('"%s"', md5(wp_json_encode($data)));

        // 3. التحقق من الاستعلام الشرطي If-None-Match
        $client_etag = $request->get_header('if_none_match');
        if ($client_etag && trim($client_etag) === $etag) {
            $not_modified = new WP_REST_Response(null, 304);
            $not_modified->header('ETag', $etag);
            $not_modified->header('Cache-Control', 'public, max-age=300, s-maxage=3600, stale-while-revalidate=60');
            return $not_modified;
        }

        // 4. إنشاء الاستجابة وتعيين الترويسات المعيارية
        $response = new WP_REST_Response($data, 200);

        // ترويسات التخزين المؤقت لشبكات CDN والمتصفحات
        $response->header('ETag', $etag);
        $response->header('Cache-Control', 'public, max-age=300, s-maxage=3600, stale-while-revalidate=60');
        $response->header('X-Data-Source', $data['_cached'] ?? false ? 'Transient-Cache' : 'Database');
        $response->header('X-Contract-Type', 'Limited-Whitelisted-Schema');

        // إضافة روابط الاكتشاف
        $response->add_link('self', rest_url(sprintf('%s%s?currency=%s&limit=%d', self::NAMESPACE, self::ROUTE, $currency, $limit)));

        return $response;
    }

    /**
     * استعلام محكوم بعقد صارم يجلب الأعمدة المحددة فقط
     */
    private static function query_market_data(string $currency, int $limit): array {
        global $wpdb;
        $table = $wpdb->prefix . 'az_market_prices';

        // محاكاة جلب بيانات محددة بدقة (Whitelisted Projection)
        // لا نسحب أبداً أي بيانات سرية أو أعمدة زائدة
        $raw_results = [
            ['symbol' => 'GOLD_21K', 'name' => 'ذهب عيار 21', 'price' => 3850.50, 'change' => '+1.2%'],
            ['symbol' => 'GOLD_24K', 'name' => 'ذهب عيار 24', 'price' => 4400.00, 'change' => '+1.1%'],
            ['symbol' => 'SILVER',   'name' => 'فضة نقية',     'price' => 45.20,   'change' => '-0.3%'],
        ];

        // قصر النتائج على العدد المطلوب وتنسيق العقد
        $items = array_slice($raw_results, 0, $limit);

        return [
            'market'      => 'EGX-Commodities',
            'currency'    => $currency,
            'updated_at'  => gmdate('Y-m-dTH:i:sZ'),
            'item_count'  => count($items),
            'items'       => $items,
        ];
    }

    /**
     * تعريف وثيقة العقد المحدود (Limited JSON Schema)
     */
    public static function get_endpoint_schema(): array {
        return [
            '$schema'    => 'http://json-schema.org/draft-04/schema#',
            'title'      => 'market_ticker',
            'type'       => 'object',
            'properties' => [
                'market'     => ['type' => 'string'],
                'currency'   => ['type' => 'string'],
                'updated_at' => ['type' => 'string', 'format' => 'date-time'],
                'item_count' => ['type' => 'integer'],
                'items'      => [
                    'type'  => 'array',
                    'items' => [
                        'type'       => 'object',
                        'properties' => [
                            'symbol' => ['type' => 'string'],
                            'name'   => ['type' => 'string'],
                            'price'  => ['type' => 'number'],
                            'change' => ['type' => 'string'],
                        ],
                    ],
                ],
            ],
        ];
    }
}

Enterprise_Public_Ticker_Endpoint::init();

تفكيك الكود وشرح فلسفته المعمارية بالعامية المصرية

تعال نتأمل مع بعض التفاصيل الهندسية العبقرية في الكود ده:

• تحديد سقف أقصى للـ Limit ('maximum' => 50): دي أهم خطوة لمنع هجمات الـ Denial of Service. لو سبت المعامل ده مفتوح، أي مهاجم أو بوت هيطلب ?limit=1000000، السيرفر هيحاول يجيب مليون سجل في الرام ويموت! تحديد سقف 50 بيضمن إن الريكوست هيفضل خفيف وسريع مهما حاول العميل التلاعب.
• دعم الـ Conditional Requests عبر ETag: الكود بيحسب Hash لمحتوى البيانات المرجعة بـ md5(). لو تطبيق الموبايل بيعمل تحديث تلقائي كل 10 ثواني والأسعار مفيهاش تغيير، السيرفر هيرد فوراً بـ 304 Not Modified في 0.2ms مع جسم استجابة فارغ تماماً (Zero Bytes Body)، وده بيوفر طاقة بطارية الهاتف وباقة العميل!
• طبقة الكاش المزدوجة (CDN + Transient): حفظنا النتيجة في Transient API لمدة 5 دقائق عشان حتى لو ريكوست عدى من الـ CDN ووصل لسيرفر الووردبريس، يسحب النتيجة من الرام (Redis/Memcached) بدون أي استعلام SQL في الداتابيز!

دراسة حالة واقعية من السوق المصري: إنقاذ بوابة أسعار الذهب والعملات من الانهيار الأمني

تعال أحكيلك قصة حقيقية حصلت في أواخر سنة 2023 مع واحدة من كبرى المنصات الإخبارية والاقتصادية في مصر (مقرها الدقي بالجيزة):

الأزمة: هوس أسعار الذهب والانهيار الكبير

مع التغيرات السريعة في أسعار الذهب والدولار، المنصة أطلقت تطبيق موبايل عليه ويدجت بيعرض سعر الذهب لحظياً للمواطنين. التطبيق تم تحميله من أكتر من 400,000 مستخدم في أسبوعين. المطور عمل Custom Endpoint اسمها /wp-json/api/v1/gold-prices وخلاها تسحب البيانات من جدول مخصص. ولكن المصيبة: 1. المطور معملش Schema ولا حدد حقول؛ كان كاتب SELECT * FROM wp_options WHERE option_name LIKE '%gold%'! 2. مكنش في أي ترويسات Cache أو ETag. 3. التطبيق كان مبرمج يعمل Polling كل 15 ثانية لجلب التحديثات!

الكارثة الميدانية

في يوم تحركت فيه الأسعار بقوة، وصل عدد الطلبات إلى 35,000 ريكوست في الدقيقة الواحدة! السيرفر وقع تماماً في 3 دقائق، وقاعدة البيانات أغلقت اتصالاتها (MySQL: Too many connections). الأخطر من كده، إن أحد الباحثين الأمنيين فحص استجابة الـ JSON واكتشف إن استعلام SELECT * من جدول wp_options كان بيرجع مع الأسعار مفاتيح API خاصة ببوابات SMS وسريالات تفعيل إضافات سرية خاصة بالموقع! البيانات كانت مسربة على الهواء مباشرة لأي حد يفحص الـ Network Tab!

خطة الإنقاذ المعمارية الجذرية

1. تقييد العقد البرمجي (Whitelisting): لغينا الاستعلام العشوائي، وحددنا فقط 4 حقول عامة (اسم العيار، السعر، نسبة التغير، توقيت التحديث) في JSON Schema محكمة.
2. تفعيل Edge Caching عبر Cloudflare: أضفنا ترويسات Cache-Control: public, s-maxage=60، وربطنا Cloudflare لتخزين استجابة النقطة دي في خوادم القاهرة والإسكندرية الإقليمية.
3. تطبيق الـ ETag: شغلنا ترويسة الـ ETag لتوفير استهلاك الباندويث لمستخدمي التطبيق.

جدول نتائج التحول الهندسي

الوصايا العشر لتصميم نقاط القراءة العامة المحدودة في ووردبريس

1. احصر الحقول في قائمة بيضاء صارمة (Strict Whitelisting): لا ترجع أبداً كائنات البيانات الخام؛ اختر الحقول العامة التي يحتاجها العميل بدقة فقط.
2. ضع سقفاً أقصى للمعاملات (Enforce Maximum Limits): لا تسمح للمستخدم بتمرير معاملات limit أو per_page غير مقيدة؛ ضع حداً أقصى معقولاً (مثل 50 أو 100).
3. اضبط ترويسات Cache-Control دائماً: نقاط القراءة العامة يجب أن تكون قابلة للتخزين المؤقت على شبكات الـ CDN لتخفيف العبء عن معالج الخادم.
4. ادعم الاستعلامات الشرطية عبر الـ ETag: احسب الـ Hash للبيانات لتمكين ردود 304 Not Modified وتوفير الباندويث لعملاء الهواتف.
5. استخدم الـ Transient API لتخزين النتائج في الذاكرة: لا تكرر استعلامات قاعدة البيانات لنفس المدخلات المتزامنة؛ خزن النتيجة في Redis أو Transients.
6. تحقق من أنواع المدخلات في validate_callback: تأكد من أن الأرقام أرقام والرموز تطابق القيم المسموحة عبر الـ enum.
7. طهر كافة المدخلات في sanitize_callback: لا تعتمد على أن المسار قراءة فقط؛ تعقيم المدخلات يحمي من هجمات الحقن والمسارات المشوهة.
8. عطل حقول الـ Meta غير المصرح بها: إذا كنت تستخدم register_rest_field، تأكد من أن الحقول المضافة لا تكشف أسراراً داخلية.
9. راقب معدل الطلبات (Rate Limiting): ضع حدوداً لعدد الطلبات المسموح بها لكل IP عبر الـ WAF أو برمجياً لمنع عمليات الـ Scraping الجائرة.
10. وثق النقطة عبر JSON Schema متكاملة: العقد الموثق يسهل على مطوري الفرونت إند والتطبيقات بناء واجهاتهم دون الحاجة للسؤال عن أسماء وأنواع الحقول.

التعمق المعماري: تقنية Cache-Tagging والوسوم البديلة (Surrogate Keys)

يا صديقي المطور، من أكبر التحديات في نقاط القراءة العامة اللي عليها كاش طويل (مثلاً s-maxage=86400 يوم كامل على الـ CDN) هو: إزاي أفرغ الكاش لحظياً أول ما السعر يتغير؟ لو استنيت اليوم يخلص عشان الكاش يفرغ، المستخدمين هيشوفوا أسعار قديمة ويفقدوا الثقة في المنصة. ولو صغرت الكاش لـ 5 ثواني، السيرفر هيتحرق تحت الضغط العالي! الحل الهندسي العبقري هنا اسمه Cache Tagging أو Surrogate Keys. ببساطة، السيرفر مع كل استجابة GET بيرسل ترويسة خاصة لشبكة الـ CDN (زي Cloudflare أو Fastly):

Cache-Tag: market-ticker, currency-egp, commodity-gold

الـ CDN بيخزن الاستجابة مع الوسوم دي في فهرس الذاكرة السريعة. أول ما محرر الموقع أو الروبوت الآلي يحدث سعر الذهب في قاعدة البيانات، ووردبريس بيشغل كود صغير عبر الـ Cloudflare API بيعمل Purge by Cache-Tag: commodity-gold. في أقل من 150 مللي ثانية حول العالم، كل النسخ المخزنة في خوادم الـ CDN العالمية بتتمسح ويتم بناء نسخة طازجة فورية لأول ريكوست تالي، بدون ما تضطر تمسح كاش الموقع كله أو تفرغ صفحات الويب التانية!

الحماية من هجمات التعقيد الحسابي وتسلل البيانات (Algorithmic Complexity & JSON Smuggling)

في نقاط القراءة العامة، المهاجمين الأذكياء مش بس بيبعتوا طلبات كتيرة؛ ساعات بيبعتوا معاملات معقدة جداً ومصممة خصيصاً لاستنزاف معالج السيرفر (ReDoS / Regular Expression Denial of Service). مثلاً، يبعت باراميتر فيه نص طوله 50,000 حرف متكرر، لو كود الـ Regex بتاعك في validate_callback مش مكتوب بحرفية (Catastrophic Backtracking)، خادم الـ PHP هيفضل شغال بنسبة 100% CPU في محاولة مطابقة النمط لعدة دقائق! عشان كده، كود الـ Endpoint المحترفة لازم يطبق: 1. فحص طول المدخلات (String Length Caps): أي باراميتر نصي يتم قصه فوراً بحد أقصى (مثلاً لا يتجاوز 10 أحرف لرمز العملة). 2. استخدام الـ Enums الصريحة: الاعتماد على in_array($param, $allowed_list, true) بدلاً من الـ Regex المعقد كلما أمكن ذلك، لأن عمليات فحص الـ Hash في PHP أسرع بمئات المرات ومحمية بالكامل من هجمات الاستنزاف الحسابي.