سرور ها می توانند پاسخ مناسب به درخواست ها بدهند. درخواست ها و پاسخ یک سری ویژگی ها و داده همراه خود دارند. کدی که در سرور درخواست را مدیریت و پاسخ را ارسال می کند وب سرویس می باشد.

در زمان ارسال درخواست Ajax در وردپرس هم از طریق جاوا اسکریپت یک درخواست به سرور می دادیم و وب سرویسی که نوشته بودیم (همان تابع قلاب شده) درخواست ما را پاسخ می داد.

Rest API در وردپرس قوانین خود را دارد که از جمله مهم ترین آن فرمت داده های پاسخ به صورت JSON (JavaScript Object Notation) می باشد.

شروع همه درخواست ها به سایت های وردپرسی از wp-json/ می باشد. هر آنچه که بعد از این لینک بیاید به عنوان یک Route شناخته می شود.

هر Route از یک سری اطلاعات تشکیل شده است :

• namespace : عبارتی که برای جلوگیری از همنام شدن api call ها می باشد. هر پلاگین با prefix خود می تواند این تغییر را ایجاد کند. مثلا “wc/v1”
• endpoints : هر عبارتی که بعد از namespace می آید که شامل :
  • methods : متدی که این api call می پذیرد. مثلا POST
  • args : آرگومان هایی که بر اساس متد این api call می پذیرد.
• _links : لینکی که در نهایت به این api call ختم میشه.

WP Rest References

یک سری وب سرویس در وردپرس به صورت پیش فرض وجود دارد که اگر به وسیله جاوا اسکریپت یا پی اچ پی یا هر زبان دیگری به آن درخواست ارسال کنید پاسخ مربوطه را بر می گرداند.

مثلا اگر به وسیله جاوااسکریپت یک درخواست به لینک /wp/v2/posts/(<id>) ارسال کنید اطلاعات پست را در قالب یک آرایه JSON به شما بر می گرداند.

در وردپرس می توان به وسیله توابع زیر درخواست به سرور ارسال کرد :

• wp_remote_get : ایجاد یک درخواست با متد get به یک سرور.
• wp_remote_post : ایجاد یک درخواست با متد post به سرور خاص. این تابع دو پارامتر می گیره که پارامتر اول url است و پارامتر دوم args می باشد که یک آرایه شامل headers و body می باشد.
• wp_remote_request : دقیقا مثل تابع قبلی عمل می کنه با این تفاوت که یک مورد با نام method دارد که می توان با آن درخواست های PUT , PATCH , DELETE هم فرستاد. سایر درخواست ها هم اگر به هدر نیاز داشته باشند می توان از این تابع استفاده کرد. به طور کل این تابع مجتمع دو تابع قبل است.

مثلا یک درخواست get به سرور میفرستیم که تعدادی پست را برای ما بر می گرداند.

$url = "http://example.com/wp-json/v2/posts/1";
$result = wp_remote_get($url);
$result_array = json_decode($result['body']);

خروجی درخواست ما شامل یک آرایه می باشد که کلید های زیر را دارا می باشد:

• headers : هدر های response
• body : محتوای بازگشتی یا همان که برنامه نویس سرور به عنوان entity-body به عنوان خروجی برای ما فرستاده.
• http_response : یک شئ از کلاس WP_HTTP_Requests_Response که شامل اطلاعاتی در رابطه با HTTP Response row می باشد.

با استفاده از تابع wp_remote_post یک درخواست به سرور وردپرسی می زنیم و یک پست می سازیم.

$url = "http://example.com/wp-json/v2/posts/1";
$args = array(
    'headers' => array(
        'Authorization' => 'Basic ' . base64_encode("admin:admin")
    ),
    'body' => array(
        'title' => 'Remote Post',
        'content' => 'post create from remote using basic auth and rest ',
        'status' => 'publish'
    )
);

$result = wp_remote_post($url, $args);

در درخواست بالا ما از basic auth استفاده کرده ایم که لازمه آن نصب پلاگین Basic-Auth می باشد. این روش ارسال username , password در Authorization می باشد که برای امنیت بیشتر از پلاگین jwt-auth می باشد.

نکته : وقتی از توابع بالا برای ارسال درخواست استفاده می کنیم CLIENT ما می شود همان سرور که تنظیمات client هم می شود تنظیمات php.ini که درخواست می فرستیم . گاهی می شود هم client و server یک دستگاه باشد.

Register Api Route

برای ساخت یک custom route باید از تابع register_rest_route در قلاب rest_api_init استفاده کنید. این تابع با توجه به تنظیمات خاص خود یک سری route را به لیست rouet ها اضافه می کند.

تابع register_rest_route پارامتر های زیر را داراست :

register_rest_route( string $namespace, string $route, array $args = array(), bool $override = false )

• namespace : یک رشته شامل دو قسمت که قسمت اول prefix پلاگین و قسمت دوم ورژن است مثلا rng/v1 .
• route : همان رشته ای که به عنوان endpoint پس از namespace با توجه به نوع عملگر این api می آید. مثلا posts/
• args : آرگومان های این custom route که شامل یک آرایه انجمنی با نام های زیر می باشد.
  • methods : متد که با استفاده از static variable های کلاس WP_REST_Server می توان به آن ها دسترسی پیدا کرد.
  • callback : تابع بازگشتی که خروجی api ما را می سازد و به عنوان ورودی یک شئ از کلاس WP_REST_Server می گیرد.
  • args : آرگومان های ورودی که در لینک داده می شود به همراه تمامی ویژگی های یک آرگومان
    • required : اجباری یا اختیاری بودن . در صورت اجباری بودن (true) و عدم آن خطا بر می گرداند.
    • default : مقدار پیش فرض این آرگومان.
    • description : توضیحات.
    • type : نوع داده (integer,string) در صورت همگانی بودن از این پارامتر استفاده نکنید.
    • validate_callback : یک تابع می گیرد که ورودی آن پارامتر arg می باشد و می توان اعتبار سنجی کرد.

method که در آرگومان args ما می فرستیم به شکل زیر است . هر گاه از هر کدام از static variable های زیر استفاده کنیم بیانگر یک مجموعه متد خاص می باشد.

WP_REST_Server : این کلاس ثوابت زیادی در رابطه با افعال http دارد که هر کدام از آن بیانگر متدهای ارسال می باشد و طی رجیستر یک route می توانیم از آن ها استفاده کنیم.

READABLE = 'GET'
CREATABLE = 'POST'
EDITABLE = 'POST, PUT, PATCH'
DELETABLE = 'DELETE'
ALLMETHODS = 'GET, POST, PUT, PATCH, DELETE'

مثلا یک custom route می سازیم که تعداد per_page پست را به صورت یک JSON Object بر گرداند.

add_action('rest_api_init', 'wli_register_routes');

function wli_register_routes() {
    register_rest_route(
        'wli/v1',
        '/posts',
        [
            'methods' => WP_REST_Server::READABLE,
            'callback' => 'wli_api_return_latest_post',
            'args' => [
                'per_page' => [
                    'required' => false,
                    'type' => 'integer',
                    'default' => 5,
                    'description' => 'posts per page',
                    'validate_callback' => function($param){
                        if($param > 0){
                            return true;
                        }else{
                            return false;
                        }
                    }
                ]
            ]
        ]
    );
}
function wli_api_return_latest_post(WP_REST_Request $request) {
    $posts_args = array(
        'post_type' => 'post',
        'posts_per_page' => $request->get_param('per_page'),
    );

    $posts = get_posts($posts_args);

    $post_array = array();
    foreach ($posts as $post) {
        $post_array[] = array(
            'ID' => $post->ID,
            'title' => $post->post_title,
        );
    }
    return $post_array;
}

هر درخواستی که توسط تابع بالا ارسال گردد یک متد دارد که بوسیله $_SERVER['REQUEST_METHOD'] می توان آن را تشخیص داد.

WP_REST_Request :  در زمان دریافت درخواست در سرور (همان تابع callback یک شئ از کلاس WP_REST_Request دریافت می کنیم که با استفاده از آن می توانیم به پارامتر های ارسالی همراه درخواست دست پیدا کنیم. به طور مثال متد get_param با توجه به ایندکس می تواند مقدار پارامتر را دریافت کند که در مثال بالا بکار گرفته شده.

هر درخواست اگر از تنظیمات خاصی (مثلا متد یا آرگومان های ضروری) که برای آن set شده است پیروی نکند خطای با پیغام مرتبط برای آن ارسال می گردد.

وقتی به wp-json برویم custom route خود را به همراه تنظیمات آن می توانیم مشاهده کنیم.

می توان از طریق endpoint هم پارامتر دریافت کرد. اگر در زمان تعریف endpoint یک عبارت منظم به شکل زیر در آن قرار دهیم().

add_action('rest_api_init', function () {
  register_rest_route( 'mytwentyseventeentheme/v1', 'posts/(?P<category_id>[\d]+)',array(
                'methods'  => 'GET',
                'callback' => 'get_latest_posts_by_category'
      ));
});

در مثال بالا ما id رو داریم که میشه از اون در تابع get_latest_posts_by_category استفاده کرد.برای دریافت این پارامتر از $request->get_param('id') استفاده می کنیم.