Что вам нужно знать о новом REST API WordPress

Опубликовано: 2018-01-25

WordPress 4.4 сделал WordPress REST API частью ядра.

В этой статье я объясню, почему эта разработка важна для WordPress (и для авторов тем и плагинов в целом), и покажу вам, как использовать ее для упрощения процесса связи между WordPress и другими приложениями.

WordPress Rest API также позволяет веб-сайтам WordPress избавиться от интерфейса администратора WordPress по умолчанию, чтобы предложить полностью персонализированный интерфейс администратора или контента с использованием разнообразного стека технологий.

Calypso — настольное приложение WordPress — прекрасный пример этого. Calypso построен с использованием одного приложения Javascript, которое использует WordPress REST API для связи между WordPress.com и ядром.

Поскольку WordPress REST API теперь является неотъемлемой частью ядра WordPress, важно, чтобы разработчики хорошо разбирались в том, как он работает, и в новых возможностях, которые он открывает для взаимодействия с WordPress.

Итак, в этом обзоре и руководстве по WordPress REST API я расскажу вам об основах WP REST API, а также покажу, как вы можете использовать его для создания (плагина) виджета, который отображает последние сообщения из Heroic Knowledge. Базовые пользовательские типы сообщений.

Введение в WordPress REST API

Прежде чем мы увидим, как использовать WordPress REST API для создания (плагина) виджета, давайте сначала немного лучше разберемся в этом термине.

Так что же означает API?

API расшифровывается как Application Program Interface .

Проще говоря, это средство связи между двумя разными приложениями.

Распространенным примером API в действии является Tweet Deck, который отображается на многих веб-сайтах. Отображение этой колоды твитов становится возможным через API, где веб-сайт просто извлекает данные из Твиттера и отображает их.

А как же отдых?

REST — это сокращение от REpresentational State Transfer .

REST — это основанный на HTML архитектурный стиль создания API. Архитектура RESTful использует HTTP-запросы для отправки, чтения, обновления и удаления данных между двумя источниками.

Поэтому, когда мы говорим о REST API, мы, по сути, имеем в виду API, использующий для связи методы HTML.

А как же JSON?

WordPress REST API имеет тот же формат, что и WordPress JSON REST API.

JSON (или нотация объектов Javascript ) — это минимальный текстовый формат обмена данными, который используется для беспрепятственного обмена данными между различными платформами (даже если платформы используют разные языки).

JSON — это облегченная альтернатива решениям на основе XML, что делает его идеальным для мобильных приложений с ограничениями пропускной способности.

Зачем использовать WordPress REST API

Вам может быть интересно, что такого исключительного в WordPress REST API и почему вы должны заботиться об этом.

Что ж… WordPress REST API позволяет вам делать больше с WordPress.

Например:

  1. Пишите приложения на любом языке, который вы знаете, и заставляйте его взаимодействовать с сайтом WordPress (единственные два требования: язык вашего приложения должен использовать методы HTML и иметь возможность интерпретировать JSON).
  2. Создавайте полностью персонализированные возможности администрирования и контента
  3. Разработка одностраничных приложений поверх WordPress

И многое другое.

Практически невозможно перечислить все потенциальные приложения/интерфейсы/возможности, которые можно создать с помощью REST API. В руководстве WordPress REST API справедливо сказано:

Наше воображение — единственный предел того, что можно сделать с помощью WordPress REST API. Суть в том, что если вам нужен структурированный, расширяемый и простой способ получения данных в WordPress и из него по HTTP, вы, вероятно, захотите использовать REST API.

Но я знаю, что реализация всегда намного сложнее, чем понимание теории.

Итак, давайте посмотрим краткое руководство о том, как вы можете использовать WordPress REST API для создания пользовательского виджета (плагина).

Краткое руководство по использованию WordPress REST API

Если у вас есть один из продуктов нашей базы знаний, например тема справочного центра KnowAll или ваша собственная тема с плагином Heroic Knowledge Base, у вас будет сайт с базой знаний статей поддержки. Использование этих продуктов не обязательно, чтобы следовать принципам этого руководства, однако помните, что вам нужно будет адаптировать любой код к вашей собственной настройке.

Итак, готовы к локальной настройке?

Здорово!

Теперь мы собираемся создать еще один веб-сайт на другом сервере.

Итак, почему мы создаем этот второй веб-сайт?

Мы делаем это, потому что хотим внедрить WordPress REST API для связи со вторым веб-сайтом, и, как вы теперь знаете, WordPress REST API предназначен для того, чтобы разговоры происходили.

Итак, мы собираемся использовать WordPress REST API, чтобы заставить два веб-сайта общаться друг с другом и обмениваться данными.

И конечная цель учебника состоит в том, чтобы:

Выберите последние опубликованные статьи базы знаний на веб-сайте справочного центра и отобразите их в виджете на боковой панели нового веб-сайта.

В этой статье веб-сайт справочного центра, на котором размещены все статьи базы знаний, будет называться « локальным » веб-сайтом, а новый веб-сайт, на котором будет отображаться виджет, будет называться « внешним » веб-сайтом.

На данный момент я предполагаю, что у вас есть 1) ваш «локальный» веб-сайт справочного центра и 2) новый «внешний» веб-сайт, настроенный на другом сервере.

И в конце урока мы бы успешно отобразили список статей базы знаний с «локального» веб-сайта на новом «внешнем» веб-сайте (через WordPress REST API) с помощью пользовательского виджета (плагина).

С этим мы готовы начать:

Шаг № 1: Начните с копирования следующего шаблонного кода в новый файл .php и сохраните его в папке плагинов вашего «внешнего» веб-сайта.

См. полный код этого руководства по REST API WordPress здесь. 

/**
* HeroThemes Example Widget
*/
class My_Widget extends WP_Widget { 

    //set up widget
    public function __construct() { 

        $widget_ops = array( 
                        'classname' => 'rest-api-test-widget',
                        'description' => 'This example provides a framework for how we will build our widget'
        );

        parent::__construct( 'my_widget', 'My Widget', $widget_ops );
    }


    /**
     * Outputs the content of the widget
     * @param array $args
     * @param array $instance
     */

    public function widget( $args, $instance ) {
        //outputs the content of the widget
        echo $args['before_widget'];

        if( !empty( $instance['title'] ) ) {
          echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'], $instance, $this->id_base ) . $args['after_title'];

        }

        // Main Widget Content Goes Here

        echo $args['after_widget'];
    }


    /**
     * Outputs the options form on admin
     * @param array $instance The widget options
     */

    public function form( $instance ) {
        //outputs the options form on admin
        $title = ( !empty( $instance['title'] ) ) ? $instance['title'] : ''; ?>

        <label for="<?php echo $this->get_field_name( 'title' ); ?>">Title: </label>

        <input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" 
        name="<?php echo $this->get_field_name( 'title' ); ?>" 
        type="text" value="<?php echo esc_attr( $title ); ?>" />
    
        <?php 
    } 

} 

 add_action( 'widgets_init', function(){ register_widget( 'My_Widget' ); } );

Этот код создает очень простой виджет, который будет отображать заголовок по вашему выбору.

Добавив код вверху шаблона и сохранив его в каталоге плагинов, мы создали его как плагин (а не добавляли код в файл функций темы).

Это небольшая вещь, но создание виджета в виде плагина в этом стиле позволяет вам включать и выключать его, а также повторно использовать его в других темах позже, если вы хотите, без необходимости копировать и вставлять.

После установки и активации у вас появится новый виджет в области виджетов панели инструментов:

виджет-админ

Шаг № 2: Используйте WordPress REST API для получения последних статей базы знаний.

Поскольку вы не хотите ничего редактировать или удалять в этой разработке, мы сосредоточимся только на функции widget(). Именно здесь содержимое виджета выводится на «внешний» веб-сайт.

Чтобы «получить» список последних статей базы знаний с «местного» веб-сайта, нам нужно знать несколько вещей:

  • Базовый путь API (какой API использовать на вашем сайте, в нашем случае последний WP API)
  • Используемый маршрут (WP API имеет несколько маршрутов для различных доступных наборов данных и операций)
  • Используемая конечная точка (какое действие должно быть выполнено)
  • Параметры (данные, связанные с запросом)

Базовый путь API всегда:

 json/wp/v2/

Таким образом, абсолютный путь API становится следующим:

 http://example.com/json/wp/v2/

(http://example.com — ваш «локальный» сайт)

Используемый маршрут:

 json/wp/v2/posts/

О конечных точках: этот маршрут на самом деле имеет три конечных точки, которые различаются методами HTTP. Эти конечные точки:

  • ПОЛУЧИТЬ
  • СТАВИТЬ
  • УДАЛИТЬ

В этом примере вы выберете конечную точку GET, чтобы получить (или «получить») список последних сообщений с «локального» веб-сайта.

Таким образом, ваша первая строка кода, взаимодействующая с REST API, будет:

$response = wp_remote_get( 'http://products-website.com/wp-json/wp/v2/posts/' );

Далее вам нужно проверить, возвращаются ли какие-либо ошибки:

if( is_wp_error( $response ) ) {
    return;
}

Все, что делает этот код, это проверяет, какой ответ возвращается. Если ответ возвращает несколько сообщений, то ошибки нет.

Последняя часть этого раздела:


$posts = json_decode( wp_remote_retrieve_body( $response ) );

if( empty( $posts ) ) {
   return;
}

$response — это строка в формате JSON с данными Post. Итак, все, что вы здесь делаете, это расшифровываете его, чтобы его можно было вывести.

Опять же, добавьте дополнительную проверку, чтобы убедиться, что $posts не пуст. Если да, то ничего не возвращается.

Итак, на данный момент вы успешно связались со своим «локальным» веб-сайтом с помощью API. Эта реализация оставляет вам список сообщений для отображения.

Следующий этап — отобразить их в вашем виджете на «внешнем» веб-сайте.

Шаг № 3: Отобразите последние сообщения на «внешнем» веб-сайте, добавив следующий код:

		if( !empty( $posts ) ) {
		
			echo '<ul>';
			foreach( $posts as $post ) {
				echo '<li><a href="' . $post->link. '">' . $post->title->rendered . '</a></li>';
			}
			echo '</ul>';
			
		}

Код готового виджета должен выглядеть так: 

/**
* HeroThemes REST API Widget
*/
class REST_API_Widget extends WP_Widget { 

	//set up widget 
	public function __construct() { 
		$widget_ops = array( 	'classname' => 'rest-api-widget',
 								'description' => 'A REST API widget that pulls posts from a different website'
 		);
 		parent::__construct( 'rest_api_widget', 'REST API Widget', $widget_ops );
 	}

	/**
	* Outputs the content of the widget
	*
	* @param array $args
	* @param array $instance
	*/
	public function widget( $args, $instance ) {
		//change this url to the WP-API endpoint for your site!
		$response = wp_remote_get( 'https://example.com/wp-json/wp/v2/ht-kb/' );

		if( is_wp_error( $response ) ) {
			return;
		}

		$posts = json_decode( wp_remote_retrieve_body( $response ) );

		if( empty( $posts ) ) {
			return;
		}

		echo $args['before_widget'];
		if( !empty( $instance['title'] ) ) {
			echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'], $instance, $this->id_base ) . $args['after_title'];
		}
		
		//main widget content
		if( !empty( $posts ) ) {
		
			echo '<ul>';
			foreach( $posts as $post ) {
				echo '<li><a href="' . $post->link. '">' . $post->title->rendered . '</a></li>';
			}
			echo '</ul>';
			
		}

		echo $args['after_widget'];
	}

	/**
	* Outputs the options form on admin
	*
	* @param array $instance The widget options
	*/
	public function form( $instance ) {
		// outputs the options form on admin
		$title = ( !empty( $instance['title'] ) ) ? $instance['title'] : '';
		?>

		<label for="<?php echo $this->get_field_name( 'title' ); ?>">Title: </label>
		<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" 
		  name="<?php echo $this->get_field_name( 'title' ); ?>" 
		  type="text" value="<?php echo esc_attr( $title ); ?>" />
		
		<?php 
	} 

 } 

 add_action( 'widgets_init', function(){ register_widget( 'REST_API_Widget' ); } );

Выполнив описанный выше шаг, когда вы теперь попытаетесь просмотреть свой «внешний» веб-сайт, вы увидите список своих сообщений с «локального» веб-сайта на боковой панели.

виджет

Это все здорово.

Однако, если вы помните, это неправильные сообщения, потому что мы хотим показать только последние статьи из базы знаний.

Наша текущая реализация этого не делает, потому что плагин базы знаний использует свой собственный настраиваемый тип записи. И поскольку пользовательские типы сообщений по умолчанию недоступны для API, это вызывает проблему. (Примечание: последняя версия базы знаний общедоступна для REST API, и следующий раздел можно пропустить)

Использование REST API с пользовательскими типами записей

Чтобы сделать пользовательские типы сообщений доступными для REST API, вам понадобится небольшой обходной путь.

Итак, при создании пользовательского типа записи вам нужно добавить новый параметр в регистр аргументов типа записи, чтобы сделать его общедоступным:


'show_in_rest' = true,
'rest_base' = 'ht_kb',
'rest_controller_class' = 'WP_REST_Posts_Controller',

Но поскольку в нашем случае мы используем подключаемый модуль для включения типа публикации статьи базы знаний, мы не будем напрямую редактировать файл подключаемого модуля, чтобы сделать настраиваемые типы записей доступными для REST API. (Прямое редактирование файла плагина никогда не бывает хорошей идеей!)

Вместо этого мы добавим следующий код в файл functions.php в дочерней теме для «локального» веб-сайта:

В последней версии KnowAll и Heroic Knowledge Base уже включена поддержка REST, ее можно отключить с помощью фильтра ht_kb_show_in_rest , но вы можете изменить приведенный ниже код для своего собственного пользовательского типа сообщений. 
/**
* Add rest support to an existing post type
*/
add_action( 'init', 'my_custom_post_type_rest_support', 25 );

function my_custom_post_type_rest_support() {
    global $wp_post_types;

    //set this to the name of your post type!
    $post_type_name = 'ht_kb';
    if( isset( $wp_post_types[ $post_type_name ] ) ) {
        $wp_post_types[$post_type_name]->show_in_rest = true;
        $wp_post_types[$post_type_name]->rest_base = $post_type_name;
        $wp_post_types[$post_type_name]->rest_controller_class = 'WP_REST_Posts_Controller';
    }
}

Теперь пользовательский тип записи «ht_kb» общедоступен для WP REST API.

После того, как пользовательский тип записи стал доступен для WordPress REST API, теперь нам нужно исправить наш виджет, чтобы он отображал записи с этим типом записи. Для этого мы вернемся к коду $response из шага 2 и обновим его до:

$response = wp_remote_get( 'http://example.com/wp-json/wp/v2/ht_kb/' );

В основном мы меняем /posts/ на /ht_kb/ в маршруте API, потому что «ht_kb» — это имя пользовательского типа записи плагина.

После обновления виджета и предварительного просмотра «внешнего» веб-сайта вы должны увидеть последние статьи из базы знаний.

виджет-kb-контент

Последние мысли

Как мы уже видели, используя несколько простых фрагментов PHP и HTML, вы можете создавать новые функции, виджеты и плагины.

Вы можете изменить плагин, который мы только что сделали, чтобы создать окно поиска, которое использует WP REST API для поиска статей в базе знаний и возвращает результаты в виджете.

Или вы можете использовать аутентификацию, чтобы контролировать, кто увидит результаты (полезно, если вы создали контент с ограниченным доступом).

Столько всего можно попробовать! Просто правильно разберитесь с основами, и все будет готово.

дальнейшее чтение

Вокруг WordPress REST API много устаревшего контента, поэтому убедитесь, что вы только что прочитали обновленный материал. В посте я давал ссылки на некоторые полезные ресурсы, но я также перечисляю некоторые из них здесь.

Поэтому прочитайте их и узнайте о различных творческих способах использования REST API.

  • Справочник по API REST
  • Часто задаваемые вопросы по API REST
  • WP REST API: к чему мы движемся?

Если у вас есть какие-либо вопросы о реализации WordPress REST API, задайте их в комментариях ниже!