REST API وردپرس: ساخت اندپوینت سفارشی، احراز هویت با Application Password، کش و امنیت

REST API وردپرس راه استاندارد صحبت کردن هر چیز دیگری با سایت شماست: اپ موبایل، فرانت هدلس با Next.js، سرویس‌های اتوماسیون، عامل‌های هوش مصنوعی و حتی خود ویرایشگر بلاکی. هر وردپرسی از نسخه‌ی ۴.۷ آن را دارد و آدرسش /wp-json/ است. این راهنما یک API واقعی برای محصولات می‌سازد: اندپوینت فهرست با فیلتر و صفحه‌بندی، اندپوینت تکی با خطای درست و اندپوینت نوشتنی که به ورود نیاز دارد. بعد احراز هویت را با چهار روش مقایسه می‌کند، کش را در چهار لایه می‌چیند و با چک‌لیست امنیت تمام می‌شود.

آنچه در این آموزش یاد می‌گیرید

• ساختار REST API وردپرس و کاوش اندپوینت‌های هسته با _fields و _embed
• ساخت اندپوینت سفارشی با register_rest_route، اعتبارسنجی ورودی و پاسخ و خطای استاندارد
• احراز هویت: کوکی و nonce برای جاوااسکریپت، Application Password برای اپ و سرویس، و کی سراغ JWT بروید
• افزودن فیلد به اندپوینت‌های موجود و نمایش متا با register_post_meta
• کش در چهار لایه: Transient، کش آبجکت، سرآیندهای HTTP و کم کردن حجم پاسخ
• امنیت: پنهان کردن کاربران، CORS محدود، محدودیت نرخ و اشتباهات رایج

REST API وردپرس چطور کار می‌کند

هر درخواست به /wp-json/ توسط وردپرس دریافت می‌شود، با مسیرهای ثبت‌شده مقایسه می‌شود، permission_callback آن مسیر اجرا می‌شود، پارامترها بر اساس args اعتبارسنجی و تمیز می‌شوند و در نهایت callback شما پاسخ را می‌سازد. هر مرحله می‌تواند با WP_Error درخواست را متوقف کند و کلاینت کد HTTP مناسب (۴۰۰، ۴۰۱، ۴۰۳ یا ۴۰۴) بگیرد. اندپوینت‌های هسته زیر wp/v2 هستند؛ قبل از ساختن چیزی جدید، آن‌ها را بشناسید:

# فهرست همه‌ی namespace ها و مسیرها
curl -s https://example.ir/wp-json/ | jq '.namespaces'

# ده نوشته‌ی آخر، فقط فیلدهای لازم
curl -s "https://example.ir/wp-json/wp/v2/posts?per_page=10&_fields=id,title,link,date"

# نوشته با تصویر شاخص و نویسنده در همان پاسخ
curl -s "https://example.ir/wp-json/wp/v2/posts/123?_embed"

# سرآیندهای صفحه‌بندی
curl -sI "https://example.ir/wp-json/wp/v2/posts?per_page=20" | grep -i x-wp-total

ساخت اندپوینت سفارشی

کد زیر یک افزونه‌ی کامل است. سه اندپوینت می‌سازد: فهرست محصولات با فیلتر دسته و صفحه‌بندی، یک محصول با شناسه، و افزودن به علاقه‌مندی‌ها که فقط برای کاربر واردشده کار می‌کند. همه‌ی ثبت‌ها روی rest_api_init است تا در درخواست‌های عادی سایت بارگذاری نشود:

<?php
/**
 * Plugin Name: API محصولات وردپرس کالا
 */

defined( 'ABSPATH' ) || exit;

add_action( 'rest_api_init', function () {
	// GET /wp-json/wpkala/v1/products?per_page=10&category=themes
	register_rest_route( 'wpkala/v1', '/products', array(
		'methods'             => WP_REST_Server::READABLE,
		'callback'            => 'wpkala_api_list_products',
		'permission_callback' => '__return_true', // عمومی، آگاهانه
		'args'                => array(
			'per_page' => array(
				'type'              => 'integer',
				'default'           => 10,
				'minimum'           => 1,
				'maximum'           => 50,
				'sanitize_callback' => 'absint',
			),
			'category' => array(
				'type'              => 'string',
				'sanitize_callback' => 'sanitize_title',
				'validate_callback' => function ( $value ) {
					return '' === $value || term_exists( $value, 'product_cat' );
				},
			),
		),
	) );

	// GET /wp-json/wpkala/v1/products/123
	register_rest_route( 'wpkala/v1', '/products/(?P<id>\d+)', array(
		'methods'             => WP_REST_Server::READABLE,
		'callback'            => 'wpkala_api_get_product',
		'permission_callback' => '__return_true',
		'args'                => array(
			'id' => array( 'type' => 'integer', 'sanitize_callback' => 'absint' ),
		),
	) );

	// POST /wp-json/wpkala/v1/products/123/favorite  (نیاز به ورود)
	register_rest_route( 'wpkala/v1', '/products/(?P<id>\d+)/favorite', array(
		'methods'             => WP_REST_Server::CREATABLE,
		'callback'            => 'wpkala_api_favorite',
		'permission_callback' => fn() => is_user_logged_in(),
		'args'                => array(
			'id' => array( 'type' => 'integer', 'sanitize_callback' => 'absint' ),
		),
	) );
} );

function wpkala_product_to_array( WP_Post $post ): array {
	return array(
		'id'    => $post->ID,
		'title' => get_the_title( $post ),
		'price' => (int) get_post_meta( $post->ID, '_price', true ),
		'image' => get_the_post_thumbnail_url( $post, 'medium' ) ?: null,
		'link'  => get_permalink( $post ),
	);
}

function wpkala_api_list_products( WP_REST_Request $request ) {
	$query_args = array(
		'post_type'      => 'product',
		'post_status'    => 'publish',
		'posts_per_page' => $request['per_page'],
		'paged'          => max( 1, (int) $request->get_param( 'page' ) ),
	);
	if ( $request['category'] ) {
		$query_args['tax_query'] = array(
			array( 'taxonomy' => 'product_cat', 'field' => 'slug', 'terms' => $request['category'] ),
		);
	}

	$query = new WP_Query( $query_args );
	$items = array_map( 'wpkala_product_to_array', $query->posts );

	$response = rest_ensure_response( $items );
	$response->header( 'X-WP-Total', (int) $query->found_posts );
	$response->header( 'X-WP-TotalPages', (int) $query->max_num_pages );
	return $response;
}

function wpkala_api_get_product( WP_REST_Request $request ) {
	$post = get_post( $request['id'] );
	if ( ! $post || 'product' !== $post->post_type || 'publish' !== $post->post_status ) {
		return new WP_Error( 'wpkala_not_found', 'محصول پیدا نشد.', array( 'status' => 404 ) );
	}
	return rest_ensure_response( wpkala_product_to_array( $post ) );
}

function wpkala_api_favorite( WP_REST_Request $request ) {
	$user_id   = get_current_user_id();
	$favorites = (array) get_user_meta( $user_id, 'wpkala_favorites', true );

	if ( in_array( $request['id'], $favorites, true ) ) {
		return new WP_Error( 'wpkala_exists', 'این محصول قبلاً در علاقه‌مندی‌ها بود.', array( 'status' => 409 ) );
	}

	$favorites[] = (int) $request['id'];
	update_user_meta( $user_id, 'wpkala_favorites', $favorites );

	$response = rest_ensure_response( array( 'favorites' => $favorites ) );
	$response->set_status( 201 );
	return $response;
}

چند نکته که این کد را از نمونه‌های اینترنتی جدا می‌کند:

• args با type و minimum و maximum. وردپرس خودش بر اساس این schema اعتبارسنجی می‌کند؛ per_page بالای ۵۰ قبل از رسیدن به کد شما با ۴۰۰ رد می‌شود.
• permission_callback صریح. حتی برای اندپوینت عمومی __return_true نوشته شده تا معلوم باشد آگاهانه عمومی است. از وردپرس ۵.۵ نبود این کلید هشدار می‌دهد.
• WP_Error با status. بدون کلید status هر خطایی ۵۰۰ برمی‌گردد و کلاینت نمی‌فهمد مشکل از او بوده یا سرور.
• سرآیندهای X-WP-Total. همان قراردادی که هسته استفاده می‌کند تا کلاینت صفحه‌بندی بسازد.
• rest_ensure_response() آرایه را به WP_REST_Response تبدیل می‌کند تا بتوانید سرآیند و کد وضعیت تنظیم کنید.

برای APIهای بزرگ‌تر، کلاس WP_REST_Controller را extend کنید؛ همان الگویی که اندپوینت‌های هسته دارند و schema، صفحه‌بندی و لینک‌های _links را استاندارد می‌کند. برای سه اندپوینت تابع ساده کافی است.

احراز هویت: چه کسی دارد درخواست می‌دهد؟

کوکی و nonce برای جاوااسکریپت داخل سایت

اگر درخواست از مرورگر کاربری می‌آید که در همان سایت وارد شده، کوکی ورود او کافی است؛ فقط باید یک nonce هم بفرستید تا وردپرس بداند درخواست از سایت خودتان است نه از سایت دیگری (محافظت CSRF). بدون nonce وردپرس درخواست را به عنوان مهمان پردازش می‌کند:

// در PHP: اسکریپت را با nonce و آدرس REST تنظیم کنید
add_action( 'wp_enqueue_scripts', function () {
	wp_enqueue_script( 'wpkala-fav', get_stylesheet_directory_uri() . '/assets/fav.js', array(), '1.0', true );
	wp_localize_script( 'wpkala-fav', 'wpkalaApi', array(
		'root'  => esc_url_raw( rest_url( 'wpkala/v1/' ) ),
		'nonce' => wp_create_nonce( 'wp_rest' ),
	) );
} );

// assets/fav.js : کاربر واردشده، بدون رمز اضافه
async function addFavorite( productId ) {
	const res = await fetch( `${ wpkalaApi.root }products/${ productId }/favorite`, {
		method: 'POST',
		headers: { 'X-WP-Nonce': wpkalaApi.nonce, 'Content-Type': 'application/json' },
		credentials: 'same-origin',
	} );
	const data = await res.json();
	if ( ! res.ok ) {
		throw new Error( data.message || 'خطای ناشناخته' );
	}
	return data.favorites;
}

در ادیتور بلاکی و هر جایی که بسته‌های وردپرس در دسترس‌اند، @wordpress/api-fetch همین کار را خودکار انجام می‌دهد:

// در ادیتور یا هر جایی که @wordpress/api-fetch در دسترس است
import apiFetch from '@wordpress/api-fetch';

const products = await apiFetch( { path: '/wpkala/v1/products?per_page=5' } );
await apiFetch( { path: '/wpkala/v1/products/123/favorite', method: 'POST' } );
// nonce و آدرس پایه را خود وردپرس تزریق می‌کند

Application Password برای اپ، اسکریپت و سرویس

برای هر چیزی خارج از مرورگر همان سایت، وردپرس از نسخه‌ی ۵.۶ رمز اپلیکیشن دارد: یک رمز جداگانه برای هر اپ یا سرویس که با Basic Auth فرستاده می‌شود، فقط روی HTTPS کار می‌کند و هر کدام جداگانه قابل باطل شدن است. قاعده‌ی مهم: برای هر سرویس یک کاربر جداگانه با کمترین نقش لازم بسازید، هرگز رمز اپ برای حساب مدیر نسازید:

# ساخت کاربر مخصوص سرویس با کمترین نقش و یک Application Password
wp user create api-mobile api@example.ir --role=subscriber
wp user application-password create api-mobile "اپ موبایل" --porcelain
# خروجی مثل: AbCd EfGh IjKl MnOp QrSt UvWx

# فراخوانی با Basic Auth (نام کاربری و رمز اپ، فاصله‌ها مهم نیست)
curl -u "api-mobile:AbCd EfGh IjKl MnOp QrSt UvWx" \
  -X POST https://example.ir/wp-json/wpkala/v1/products/123/favorite

# دیدن و باطل کردن رمزها
wp user application-password list api-mobile
wp user application-password delete api-mobile --all

همین روش برای اتصال ابزارهای اتوماسیون مثل n8n، سرویس‌های هوش مصنوعی و MCP Adapter که در مقاله‌ی اتصال وردپرس به هوش مصنوعی توضیح دادیم استفاده می‌شود. اگر هاست شما سرآیند Authorization را حذف می‌کند (در بعضی تنظیمات آپاچی با FastCGI)، این خط را به .htaccess اضافه کنید: SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1.

JWT و OAuth: کی لازم می‌شوند

وقتی اپ شما کاربر نهایی دارد که با نام کاربری و رمز خودش وارد می‌شود (مثل اپ فروشگاه با ثبت‌نام مشتری)، به توکنی با انقضا نیاز دارید که بعد از ورود صادر شود. این JWT است و در هسته نیست؛ افزونه‌هایی برای آن وجود دارد که با کلید مخفی در wp-config کار می‌کنند. OAuth 2 برای وقتی است که سرویس‌های دیگر باید با اجازه‌ی کاربر به سایت شما وصل شوند؛ برای پلتفرم‌ها معنی دارد و برای یک فروشگاه معمولاً زیادی است.

افزودن فیلد به اندپوینت‌های موجود

لازم نیست برای هر داده اندپوینت جدید بسازید. با register_rest_field فیلد محاسبه‌شده به پاسخ نوشته‌ها اضافه می‌کنید و با register_post_meta و show_in_rest متای سفارشی را هم برای خواندن و هم نوشتن باز می‌کنید؛ همین کار باعث می‌شود ویرایشگر بلاکی هم آن متا را ببیند:

// افزودن فیلد به اندپوینت‌های موجود هسته: GET /wp/v2/posts حالا reading_time دارد
add_action( 'rest_api_init', function () {
	register_rest_field( 'post', 'reading_time', array(
		'get_callback' => function ( $post ) {
			$words = str_word_count( wp_strip_all_tags( get_post_field( 'post_content', $post['id'] ) ) );
			return max( 1, (int) ceil( $words / 200 ) );
		},
		'schema'       => array( 'type' => 'integer', 'description' => 'زمان مطالعه به دقیقه', 'readonly' => true ),
	) );
} );

// نمایش و ویرایش متا از طریق REST (برای ادیتور بلاکی و اپ)
add_action( 'init', function () {
	register_post_meta( 'post', 'wpkala_subtitle', array(
		'type'          => 'string',
		'single'        => true,
		'show_in_rest'  => true,
		'sanitize_callback' => 'sanitize_text_field',
		'auth_callback' => fn() => current_user_can( 'edit_posts' ),
	) );
} );

کش: چهار لایه برای API سریع

REST API وردپرس به طور پیش‌فرض کش نمی‌شود و هر درخواست کل وردپرس را بارگذاری می‌کند. برای اپی که هر ثانیه ده‌ها درخواست می‌زند این یعنی سرور زیر بار. ساده‌ترین لایه Transient است که در جدول options می‌ماند و اگر کش آبجکت (Redis) فعال باشد خودکار به آن منتقل می‌شود:

function wpkala_api_list_products( WP_REST_Request $request ) {
	$key    = 'wpkala_products_' . md5( wp_json_encode( $request->get_params() ) );
	$cached = get_transient( $key );
	if ( false !== $cached ) {
		return rest_ensure_response( $cached );
	}

	// ... همان کوئری قبلی ...
	$items = array_map( 'wpkala_product_to_array', $query->posts );

	set_transient( $key, $items, 5 * MINUTE_IN_SECONDS );
	return rest_ensure_response( $items );
}

// پاک کردن کش وقتی محصولی تغییر کرد
add_action( 'save_post_product', function () {
	global $wpdb;
	$wpdb->query( "DELETE FROM {$wpdb->options} WHERE option_name LIKE '_transient_wpkala_products_%' OR option_name LIKE '_transient_timeout_wpkala_products_%'" );
} );

برای پاسخ‌های عمومی یک لایه بیرون‌تر هم بروید و به CDN یا nginx بگویید پاسخ را نگه دارد. دقت کنید این سرآیند فقط برای کاربر مهمان و متد GET فرستاده شود:

// سرآیند کش فقط برای پاسخ‌های عمومی namespace خودتان
add_filter( 'rest_post_dispatch', function ( $response, $server, $request ) {
	if ( str_starts_with( $request->get_route(), '/wpkala/v1/products' ) && 'GET' === $request->get_method() && ! is_user_logged_in() ) {
		$response->header( 'Cache-Control', 'public, max-age=300, stale-while-revalidate=60' );
	}
	return $response;
}, 10, 3 );

• پارامتر _fields را در مستندات API خودتان توصیه کنید؛ کلاینت‌ها فقط آنچه لازم دارند می‌گیرند.
• در فهرست‌ها هرگز محتوای کامل نوشته را برنگردانید؛ خلاصه کافی است و جزئیات در اندپوینت تکی.
• کلید کش را از همه‌ی پارامترها بسازید وگرنه کاربر دسته‌ی قالب‌ها نتیجه‌ی دسته‌ی افزونه‌ها را می‌بیند.
• با افزونه‌ی Query Monitor تعداد کوئری هر درخواست REST را ببینید؛ عدد بالای ۳۰ یعنی جای کش یا بازنویسی کوئری.

امنیت REST API

اشتباه رایج این است که به خاطر امنیت کل REST API را غیرفعال کنند؛ ویرایشگر بلاکی، ووکامرس و بیشتر افزونه‌ها از کار می‌افتند. به جای آن نقاط حساس را ببندید:

// فهرست کاربران فقط برای واردشده‌ها
add_filter( 'rest_endpoints', function ( $endpoints ) {
	if ( ! is_user_logged_in() ) {
		unset( $endpoints['/wp/v2/users'], $endpoints['/wp/v2/users/(?P<id>[\d]+)'] );
	}
	return $endpoints;
} );

// CORS فقط برای دامنه‌ی اپ خودتان
add_action( 'rest_api_init', function () {
	remove_filter( 'rest_pre_serve_request', 'rest_send_cors_headers' );
	add_filter( 'rest_pre_serve_request', function ( $value ) {
		$allowed = array( 'https://app.example.ir', 'http://localhost:3000' );
		$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, OPTIONS' );
			header( 'Access-Control-Allow-Headers: Authorization, Content-Type, X-WP-Nonce' );
			header( 'Access-Control-Allow-Credentials: true' );
			header( 'Vary: Origin' );
		}
		return $value;
	} );
} );

# nginx: محدودیت نرخ برای مسیر REST (در بلاک http و server)
limit_req_zone $binary_remote_addr zone=wpapi:10m rate=10r/s;

location ~ ^/wp-json/ {
    limit_req zone=wpapi burst=20 nodelay;
    try_files $uri $uri/ /index.php?$args;
}

• اندپوینت wp/v2/users نام‌های کاربری را به مهمان نشان می‌دهد و اولین قدم حمله‌ی brute force است؛ کد بالا آن را فقط برای واردشده‌ها باز می‌گذارد.
• CORS را به دامنه‌های مشخص محدود کنید. سرآیند Access-Control-Allow-Origin: * همراه با کوکی یعنی هر سایتی می‌تواند به نام کاربر شما درخواست بزند.
• محدودیت نرخ را در وب‌سرور بگذارید نه در PHP؛ وقتی درخواست به PHP برسد هزینه‌اش پرداخت شده.
• هر ورودی را با sanitize تمیز و با validate رد کنید، حتی اگر فقط اپ خودتان درخواست می‌زند؛ هر کسی می‌تواند درخواست اپ شما را تکرار کند.
• در پاسخ خطا جزئیات داخلی (نام جدول، مسیر فایل، پیام SQL) برنگردانید.
• لاگ درخواست‌های ناموفق ۴۰۱ و ۴۰۳ را نگه دارید؛ الگوی حمله قبل از موفقیتش دیده می‌شود.

REST API یا Abilities API؟

وردپرس ۶.۹ لایه‌ی جدیدی به نام Abilities API اضافه کرد که قابلیت‌های سایت را با schema و مجوز برای ابزارها و عامل‌های هوش مصنوعی توصیف می‌کند و خودش یک REST هم زیر wp-abilities/v1 دارد. این جایگزین REST API نیست: REST همچنان راه اصلی اپ‌ها و فرانت هدلس است. اگر قابلیتی می‌سازید که قرار است Claude یا Cursor از طریق MCP صدا بزند، آن را به عنوان Ability ثبت کنید؛ اگر اپ موبایل یا سایت Next.js دارید، REST بسازید. هر دو می‌توانند از همان توابع PHP داخلی استفاده کنند.

خطاهای رایج و راه‌حل