ساخت API اختصاصی برای وردپرس

ساخت API اختصاصی در وردپرس، یکی از قابلیت‌هایی است که مرزهای سایت شما را جابه‌جا می‌کند. تجربه‌ام: پروژه‌هایی که API اختصاصی دارند، در اتصال به اپلیکیشن موبایل، داشبورد خارجی، یا سرویس‌های تحلیل، بسیار چابک‌تر هستند. خبر خوب اینکه وردپرس از نسخهٔ ۴.۷ یک REST API کامل دارد که ساخت endpoint اختصاصی را ساده کرده. خبر متوسط اینکه بیشتر پروژه‌ها به‌خاطر ترس از امنیت، سراغش نمی‌روند؛ در حالی که با رعایت چند قاعده، امنیت آن تضمین‌شدنی است. این مقاله، ساخت API اختصاصی را از پایه تا امنیت مرور می‌کند. اگر با مفاهیم پایه آشنا نیستید، REST API وردپرس و API چیست و چه کاربردی دارد را پیش از ادامه ببینید.

چرا API اختصاصی؟

چهار سناریوی رایج: یک — اپلیکیشن موبایل: اپ iOS/Android، داده را از سایت می‌خواند. دو — داشبورد خارجی: پنل مدیریت جدا، داده را از سایت می‌گیرد. سه — ادغام با سرویس خارجی: CRM، سیستم انبار، سرویس تحلیل. چهار — Headless: فرانت‌اند مدرن (React/Vue) که از API تغذیه می‌کند. تجربه‌ام: در پروژه‌ای با اپ موبایل، REST API اختصاصی، جایگزین ۴۰٪ کدهای تکراری شد. مسیر Headless در استفاده از REST API و اتصال وردپرس به سرویس‌های خارجی.

API اختصاصی، دروازهٔ سایت شما به دنیای بیرون است. مثل هر دروازه، باید محکم، قابل کنترل، و قابل بازرسی باشد.

REST API در وردپرس: مرور سریع

REST API از پیش‌فرض در وردپرس فعال است. مسیر پایه: /wp-json/. مثلاً /wp-json/wp/v2/posts، تمام نوشته‌ها را برمی‌گرداند. سه مفهوم کلیدی: route: مسیر endpoint. namespace: پیشوندی برای گروه endpoints، مثل wp/v2 یا my-plugin/v1. endpoint: ترکیب مسیر و متد HTTP. مثال‌های بیشتر در راهنمای REST API وردپرس.

ثبت یک endpoint سفارشی

اسکلت پایه:

function my_plugin_register_api() {
    register_rest_route(
        'my-plugin/v1',
        '/stats',
        array(
            'methods'             => 'GET',
            'callback'            => 'my_plugin_get_stats',
            'permission_callback' => 'my_plugin_check_permission',
        )
    );
}
add_action( 'rest_api_init', 'my_plugin_register_api' );

سه نکتهٔ کلیدی: یک — hook rest_api_init: نه init. دو — namespace اختصاصی: همیشه با نام افزونه/پروژه، نسخه‌گذاری‌شده (مثل my-plugin/v1). سه — permission_callback: الزامی. بدون آن، در نسخه‌های جدید وردپرس، اخطار و در نسخه‌های آینده، رد می‌شود. راهنمای hook در هوک‌های وردپرس.

متدهای HTTP و semantic

از متدهای HTTP به‌درستی استفاده کنید: GET: خواندن داده. POST: ساخت منبع جدید. PUT/PATCH: به‌روزرسانی کامل/جزئی. DELETE: حذف. تجربه‌ام: بیشتر endpointهای آماتور، همه‌چیز را با GET و POST انجام می‌دهند — این انتخاب، امنیت و کش را پیچیده می‌کند. مصرف‌کننده‌های API (اپلیکیشن‌ها، ابزارها) انتظار دارند که GET بی‌خطر و idempotent باشد. اگر endpoint با GET، داده را تغییر دهد، خطر CSRF و مشکلات cache اجتناب‌ناپذیر است.

Callback و ساختار پاسخ

Callback باید داده را با WP_REST_Response یا آرایه/شیء برگرداند:

function my_plugin_get_stats( WP_REST_Request $request ) {
    $period = $request->get_param( 'period' );
    $data = array(
        'period'    => $period,
        'visitors'  => 1234,
        'generated' => current_time( 'mysql' ),
    );
    return new WP_REST_Response( $data, 200 );
}

نکته: همیشه WP_REST_Response با کد وضعیت صریح برگردانید. برای خطا، WP_Error:

if ( empty( $period ) ) {
    return new WP_Error(
        'missing_period',
        'پارامتر period الزامی است.',
        array( 'status' => 400 )
    );
}

permission_callback و امنیت

permission_callback، دروازهٔ امنیت endpoint شماست. سه الگوی رایج:

// برای endpoint عمومی - همه دسترسی دارند
function my_plugin_public_permission() {
    return true;
}

// فقط کاربران لاگین‌شده
function my_plugin_user_permission() {
    return is_user_logged_in();
}

// فقط ادمین با capability خاص
function my_plugin_admin_permission() {
    return current_user_can( 'manage_options' );
}

تذکر مهم: هرگز permission_callback را حذف نکنید یا به __return_true ندهید بدون دلیل روشن. تجربه‌ام: در پرونده‌های امنیتی که بررسی کرده‌ام، بیشترین آسیب‌پذیری‌های REST API، از همین نقطهٔ کوچک آمده — یک endpoint که قرار بود «فقط برای تست» باشد ولی عمومی ماند. راهنمای امنیت در PHP امن در وردپرس و افزونه‌های امنیتی.

احراز هویت در API

سه روش احراز هویت در REST API وردپرس: یک — Cookie Authentication: پیش‌فرض وردپرس. برای درخواست‌های از پیشخوان و ابزارهای خود سایت. مناسب نیست برای اپلیکیشن‌های بیرونی. دو — Application Passwords: از وردپرس ۵.۶ به‌صورت داخلی. ساده‌ترین راه برای ادغام با سرویس بیرونی. سه — JWT Authentication: با افزونه. مناسب اپلیکیشن‌های موبایل و Headless. تجربه‌ام: در پروژه‌های Headless مدرن، JWT انتخاب اول است — با توکن قابل انقضا و امکان revoke. الگوهای دقیق در راهنمای REST API و احراز هویت API.

اعتبارسنجی پارامترها

REST API وردپرس، امکان تعریف اعتبارسنجی برای هر پارامتر را می‌دهد:

register_rest_route( 'my-plugin/v1', '/stats', array(
    'methods'  => 'GET',
    'callback' => 'my_plugin_get_stats',
    'permission_callback' => 'my_plugin_check_permission',
    'args' => array(
        'period' => array(
            'required' => true,
            'type'     => 'string',
            'enum'     => array( 'day', 'week', 'month' ),
            'sanitize_callback' => 'sanitize_text_field',
        ),
    ),
) );

مزیت: وردپرس خودکار پارامترها را بررسی و sanitize می‌کند. اگر نوع اشتباه یا مقدار نامعتبر باشد، خطای ۴۰۰ برمی‌گردد. راهنمای کامل در اعتبارسنجی داده‌ها و پاک‌سازی داده‌ها.

الگوهای پیشرفته

برای توسعه‌دهنده‌های سطح بالا، سه الگوی پیشرفته: یک — Versioning: همیشه namespace را با v1، v2 دنبال کنید. تغییرات شکننده را در namespace جدید اضافه کنید و نسخهٔ قدیم را برای مدتی حفظ کنید. این، تفاوت بین یک API پایدار و یک API شکننده است. دو — Cache-Control: برای endpointهای GET، هدرهای cache تنظیم کنید. وردپرس به‌طور خودکار این کار را نمی‌کند. با rest_post_dispatch هدرها را اضافه کنید. سه — Batching: اگر مصرف‌کننده نیاز به چند درخواست دارد، یک endpoint batch بسازید که چند query را یک‌جا برمی‌گرداند. تجربه‌ام: در پروژه‌ای با اپ موبایل، batching زمان بارگذاری را ۴۰٪ کاهش داد. الگوهای دقیق در راهنمای REST API و بهینه‌سازی عملکرد REST API. یک نکته: در endpointهای حساس، rate limiting را در سطح سرور (Nginx) یا با افزونه اعمال کنید — وردپرس به‌تنهایی این قابلیت را ندارد.

مصرف API از بیرون

برای مصرف API از سرویس خارجی، سه نکته: یک — استفاده از wp_remote_get و wp_remote_post. نه curl یا file_get_contents. این توابع، وردپرس‌سازگار و قابل تست با فیلترها هستند. دو — مدیریت خطا: همیشه is_wp_error را چک کنید و در صورت خطا، از cache یا مقدار پیش‌فرض استفاده کنید. سه — Timeout: همیشه timeout مناسب بگذارید تا سایت شما به‌خاطر سرویس بیرونی کند نشود. الگوی کامل در اتصال وردپرس به سرویس‌های خارجی و توابع وردپرس برای HTTP.

اشتباهات رایج

• permission_callback خالی یا __return_true بدون دلیل: خطر امنیتی جدی.
• ثبت endpoint روی init: باید rest_api_init باشد.
• نادیده‌گرفتن namespace: احتمال تعارض با endpoints وردپرس یا افزونه‌های دیگر.
• نبود validation روی پارامترها: خطای ۵۰۰ در ورودی‌های بد.
• برگرداندن داده خام بدون escape: خطر XSS در مصرف‌کننده.
• نبود versioning: تغییر شکننده، همهٔ مصرف‌کننده‌ها را می‌شکند.
• استفاده از GET برای تغییر داده: خطر CSRF و مشکلات cache.
• نبود rate limiting: endpoint عمومی بدون محدودیت، قربانی DDoS.
• نادیده‌گرفتن timeout در درخواست به سرویس خارجی: کندی سایت.
• نبود لاگ درخواست‌ها: دیباگ در بحران دشوار.

جمع‌بندی

ساخت API اختصاصی در وردپرس، شش گام دارد: ثبت endpoint با register_rest_route، انتخاب متد HTTP درست، نوشتن callback، تعریف permission_callback، اعتبارسنجی پارامترها، و مدیریت احراز هویت. اگر امروز فقط یک کار می‌کنید: یک endpoint سادهٔ GET /my-plugin/v1/hello بسازید و در مرورگر باز کنید. همان اولین تجربه، درهای زیادی باز می‌کند. تجربهٔ خودتان از ساخت API اختصاصی، در دیدگاه‌ها ارزشمند است. 🔌