REST API در وردپرس راهنمای کامل
چرا REST API در وردپرس برای بسیاری از توسعهدهندگان همچنان ناشناخته است و چطور میتوان از آن برای ساخت اپلیکیشن‌های مدرن استفاده کرد؟
اولین باری که وردپرس را به یک اپلیکیشن موبایل وصل کردم، همه فکر می‌کردند باید دیتابیس را مستقیم خواند. اما یک راه تمیزتر وجود داشت که خیلی‌ها از آن بی‌خبرند: REST API وردپرس. با آن، اپلیکیشن موبایل به همان ساختار داده‌ای وصل می‌شود که پیشخوان وردپرس استفاده می‌کند. اگر با مفهوم کلی API آشنا نیستید، API چیست نقطه شروع خوبی است.
REST API وردپرس دقیقاً چیست؟
از وردپرس نسخه ۴.۷، یک REST API داخلی به هسته اضافه شد که اجازه می‌دهد از خارج از پیشخوان، با محتوای وردپرس کار کنید. این API مبتنی بر اصول REST (Representational State Transfer) است و با JSON (JavaScript Object Notation) کار می‌کند. مسیر پایه آن /wp-json/wp/v2/ است و هر منبع داخلی مثل posts، pages، users و media یک endpoint مشخص دارد.
مزیت اصلی این API، یکسان‌سازی دسترسی است. ویرایشگر گوتنبرگ از همین API برای ذخیره محتوا استفاده می‌کند. اپلیکیشن‌های موبایل، سرویس‌های خارجی و حتی اسکریپت‌های CLI هم می‌توانند از همین مسیر استفاده کنند. اگر با اصول طراحی REST آشنا نیستید، اصول طراحی REST API راهنمای جامعی دارد.
REST API وردپرس یک لایه اضافه نیست؛ زیرساخت داخلی است که کل اکوسیستم مدرن وردپرس روی آن بنا شده است.
endpointهای داخلی که باید بشناسید
وردپرس چند endpoint پرکاربرد دارد که در پروژه‌های مختلف با آن‌ها کار کرده‌ام:
| Endpoint | کاربرد | متد |
|---|---|---|
/wp/v2/posts | خواندن و ساخت نوشته | GET, POST, PUT, DELETE |
/wp/v2/pages | خواندن و ساخت برگه | GET, POST, PUT, DELETE |
/wp/v2/users | مدیریت کاربران | GET, POST, PUT, DELETE |
/wp/v2/media | مدیریت فایل‌های رسانه | GET, POST, DELETE |
/wp/v2/categories | مدیریت دسته‌بندی‌ها | GET, POST, PUT, DELETE |
/wp/v2/tags | مدیریت برچسب‌ها | GET, POST, PUT, DELETE |
در پروژه‌های واقعی، دو نکته مهم درباره این endpointها وجود دارد. اول، صفحه‌بندی: به صورت پیش‌فرض، هر درخواست فقط ده آیتم برمی‌گرداند. برای دریافت بیشتر، باید از پارامترهای page و per_page استفاده کنید. دوم، فیلدهای اضافه: پاسخ‌های پیش‌فرض شامل فیلدهای زیادی هستند که ممکن است لازم نباشند. با پارامتر _fields می‌توانید دقیقاً فیلدهای موردنیاز را تعیین کنید.
اگر با ساختار JSON آشنا نیستید، JSON چیست و چگونه داده‌ها را ساختاردهی می‌کند پیش‌نیاز مفیدی است. برای کار با داده‌های پیچیده‌تر، کار با JSON در پروژه‌های واقعی نکات کاربردی دارد.
احراز هویت در REST API وردپرس
REST API وردپرس در حالت پیش‌فرض، دسترسی خواندن به محتوای منتشرشده را آزاد می‌گذارد. اما برای عملیات نوشتن، حذف یا خواندن محتوای منتشرنشده، احراز هویت لازم است. سه روش اصلی برای احراز هویت وجود دارد: Cookie Authentication که برای پلاگین‌های داخلی استفاده می‌شود، Application Passwords که از وردپرس ۵.۶ به هسته اضافه شده، و OAuth که برای اپلیکیشن‌های خارجی مناسب است.
Application Passwords ساده‌ترین روش برای شروع است. در پروفایل کاربر، یک رمز مخصوص اپلیکیشن می‌سازید و از آن در هدر Authorization استفاده می‌کنید. برای اپلیکیشن‌های موبایل و سرویس‌های خارجی، این روش انتخاب اول من است. برای درک اصول کلی، احراز هویت در API و احراز هویت در REST API راهنمای کاملی دارند.
نکته مهم امنیتی: هرگز رمز اصلی کاربر را در اپلیکیشن‌های خارجی ذخیره نکنید. Application Password برای همین منظور ساخته شده و می‌تواند به صورت مستقل revoke شود. برای مدیریت امن رمزها، اصول مدیریت رمز عبور امن را ببینید. برای فعال‌سازی 2FA روی حساب کاربر، فعال‌سازی 2FA برای کاربران وردپرس راهنمای کاربردی است.
ساخت endpoint سفارشی
یکی از قدرتمندترین قابلیت‌های REST API وردپرس، امکان افزودن endpoint سفارشی است. با تابع register_rest_route می‌توانید مسیر جدید بسازید، callback تعریف کنید و سطح دسترسی را مشخص کنید. این قابلیت در پروژه‌های خاص که داده‌های سفارشی دارند بسیار کارآمد است.
ساختار پایه یک endpoint سفارشی شامل سه بخش است: namespace که معمولاً شامل نام سایت یا افزونه است، route که مسیر endpoint را تعیین می‌کند، و args که پارامترها و validation را توصیف می‌کند. برای آشنایی با هوک‌هایی که این قابلیت را ممکن می‌کنند، هوک‌های وردپرس چیستند و چگونه کار می‌کنند پیش‌نیاز مفیدی است.
در پیاده‌سازی، دو نکته را جدی بگیرید. اول، permission_callback باید دقیق باشد و سطح دسترسی را بررسی کند. بدون آن، endpoint شما به روی همه باز است. دوم، پارامترها باید validate و sanitize شوند. برای اصول امنیتی کد سفارشی، نوشتن کد PHP امن برای وردپرس راهنمای کاملی است. برای ساخت endpoint در PHP خالص که در پروژه‌های وردپرسی هم مفید است، ساخت API با PHP را ببینید.
REST API و ووکامرس
ووکامرس REST API اختصاصی خودش را دارد که در مسیر /wp-json/wc/v3/ قرار دارد. این API تقریباً همه بخش‌های فروشگاه را پوشش می‌دهد: محصولات، سفارش‌ها، مشتریان، کوپن‌ها، مالیات، ارسال و گزارش‌ها. در پروژه‌های فروشگاهی، این API ابزار اصلی برای اتصال به سرویس‌های خارجی مثل انبار، حسابداری و پست است.
احراز هویت در API ووکامرس با Consumer Key و Consumer Secret انجام می‌شود. این دو کلید در صفحه تنظیمات REST API ووکامرس ساخته می‌شوند و هرکدام یک سطح دسترسی دارند. یک اصل امنیتی که در پروژه‌ها همیشه رعایت می‌کنم: کمترین دسترسی لازم را بدهید. اگر یک سرویس فقط می‌خواهد سفارش‌ها را بخواند، فقط سطح Read بدهید. راهنمای کامل این بخش در اتصال ووکامرس به API های خارجی آمده است.
اگر با مدیریت محصولات از طریق API کار می‌کنید، به ویژه برای variable product و مدیریت موجودی، درک ساختار داده ضروری است. برای ساخت محصول متغیر به صورت دستی، ساخت محصول متغیر در ووکامرس و برای مدیریت موجودی، مدیریت موجودی محصولات در ووکامرس راهنمای کاملی دارند.
Headless WordPress و کاربردهای مدرن
یکی از کاربردهای جذاب REST API وردپرس، معماری Headless است. در این معماری، وردپرس فقط نقش CMS (Content Management System) ایفا می‌کند و فرانت‌اند با یک فریم‌ورک جدا مثل React یا Vue ساخته می‌شود. اپلیکیشن فرانت‌اند از طریق REST API به وردپرس وصل می‌شود و محتوا را می‌گیرد.
مزیت Headless WordPress در سه چیز است. اول، سرعت: فرانت‌اند ایستا یا نیمه‌ایستا بسیار سریع‌تر از یک سایت وردپرسی سنتی است. دوم، انعطاف: می‌توانید رابط کاربری را کاملاً آزاد طراحی کنید. سوم، چند‌پلتفرمی: یک CMS می‌تواند هم سایت و هم اپلیکیشن موبایل و هم ویجت‌های تعبیه‌شده را تغذیه کند. نقطه ضعفش، از دست دادن پیشخوان وردپرس در فرانت‌اند است که در برخی پروژه‌ها مشکل‌ساز می‌شود. برای ساخت فرانت‌اند مدرن، React از صفر و Vue.js برای مبتدیان راهنمای مفیدی هستند.
برای پیاده‌سازی Headless، معمولاً از کتابخانه‌هایی مثل axios یا fetch استفاده می‌شود که درخواست HTTP می‌فرستند. اگر با نحوه مدیریت خطای HTTP آشنا نیستید، پیدا کردن خطاهای جاوااسکریپت در کنسول و Fetch API در جاوااسکریپت نقاط شروع خوبی هستند.
نکات امنیتی که در پروژه‌ها نجات‌دهنده بودند
چند اصل امنیتی که در پروژه‌های وردپرسی با REST API به آن‌ها رسیدم:
- محدودسازی سطح دسترسی: هر endpoint باید دقیقاً تعریف کند چه کسی می‌تواند به آن دسترسی داشته باشد.
- Rate Limiting: روی endpointهای عمومی و حساس، محدودسازی نرخ درخواست ضروری است.
- Sanitize و Validation: هر ورودی باید پاک‌سازی شود و با schema مشخص بررسی شود.
- HTTPS اجباری: همه درخواست‌ها باید از HTTPS استفاده کنند.
- لاگ‌گیری دقیق: درخواست‌های 401 و 403 باید در لاگ‌ها برجسته شوند.
برای اصول کامل امنیت API، امنیت API و بهترین روش‌ها و چگونه REST API امن بسازیم را ببینید. برای حملات رایج مثل CSRF و XSS که روی API هم اثر دارند، CSRF چیست و چگونه از آن جلوگیری کنیم و حملات XSS راهنمای کاملی دارند.
در API، امنیت از یک لایه واحد نمی‌آید. از ترکیب احراز هویت، مجوزدهی، اعتبارسنجی ورودی، محدودسازی نرخ و پایش فعال ساخته می‌شود.
پرسش‌های پرتکرار درباره REST API وردپرس
آیا REST API وردپرس به صورت پیش‌فرض فعال است؟ بله، از نسخه ۴.۷ در هسته قرار دارد. برای غیرفعال‌سازی آن باید از فیلتر استفاده کنید اما این کار توصیه نمی‌شود چون خیلی از قابلیت‌های داخلی به آن وابسته‌اند.
چگونه می‌توانم endpoint جدید بسازم؟ با تابع register_rest_route در فایل functions.php یا در یک افزونه سفارشی. برای پیاده‌سازی امن، permission_callback را جدی بگیرید.
آیا می‌توانم داده‌های متادیتا را از طریق API بخوانم؟ بله اما باید در ثبت متادیتا، show_in_rest را فعال کنید. بدون این، متادیتا در پاسخ API ظاهر نمی‌شود.
تفاوت Application Passwords و OAuth چیست؟ Application Passwords ساده‌تر است و برای اپلیکیشن‌های خودتان مناسب است. OAuth برای دسترسی تفویضی به سرویس‌های خارجی طراحی شده و پیچیده‌تر اما استانداردتر است.
آیا REST API روی سرعت سایت اثر می‌گذارد؟ خود API روی سرعت فرانت‌اند سایت اثر مستقیم ندارد اما اگر تعداد درخواست‌های API بالا باشد، بار سرور افزایش می‌یابد. برای بهینه‌سازی، بهینه‌سازی عملکرد REST API را ببینید.
برای اتصال ووکامرس به سرویس‌های خارجی، اتصال ووکامرس به API های خارجی راهنمای جامعی است. اگر با GraphQL هم کار می‌کنید، تفاوت REST و GraphQL و GraphQL یا REST در پروژه‌های واقعی نکات مهمی دارند.
برای مستندسازی API وردپرس، مستندسازی API و مستندسازی REST API با Swagger را ببینید. برای کاربردهای عملی‌تر، استفاده از REST API در وردپرس و REST API در عمل راهنمای کاملی هستند. اگر با امنیت وردپرس آشنا نیستید، راهنمای امنیت وردپرس برای مبتدیان نقطه شروع خوبی است. برای آشنایی با ویکی‌پدیا در این موضوع، وردپرس در ویکی‌پدیا توضیحات جامعی دارد.
آنچه از پروژه‌های واقعی یاد گرفتم
سه چیز بعد از سال‌ها کار با REST API وردپرس در ذهنم جا افتاده. اول، این API فقط یک افزودنی نیست؛ زیرساخت اصلی وردپرس مدرن است. دوم، اگر می‌خواهید اپلیکیشن یا سرویس خارجی بسازید، REST API تمیزترین مسیر است. سوم، امنیت و مستندسازی را از همان روز اول جدی بگیرید. برای کار با ابزارهای توسعه‌ای که در این مسیر کمک می‌کنند، استفاده از REST API در وردپرس و REST API در وردپرس را ببینید. برای تست API، تست API و تست REST API با Postman راهنمای عملی هستند. برای اتصال به سرویس‌های بیرونی، ساخت REST API با پایتون و ساخت API با PHP نکات ارزشمندی دارند.
اگر تجربه‌ای از کار با REST API وردپرس در پروژه‌ای واقعی دارید، در دیدگاه بنویسید. برای من جالب است بدانم از کدام endpoint بیشترین استفاده را کرده‌اید و چه چالشی در این مسیر داشته‌اید. 🔌
نویسنده در وردپرس کار.