O que você precisa saber sobre a nova API REST do WordPress
Publicados: 2018-01-25O WordPress 4.4 tornou a API REST do WordPress parte do núcleo.
Neste artigo, explicarei por que esse desenvolvimento é enorme para o WordPress (e autores de temas e plugins em geral) e mostrarei como usá-lo para simplificar o processo de comunicação entre o WordPress e outros aplicativos.
A API Rest do WordPress também possibilita que os sites do WordPress se livrem da interface de administração padrão do WordPress para oferecer experiências de administração ou conteúdo completamente personalizadas usando uma pilha de tecnologia diversificada.
Calypso – aplicativo de desktop do WordPress – é um belo exemplo disso. O Calypso é construído usando um único aplicativo Javascript que usa a API REST do WordPress para se comunicar entre o WordPress.com e o núcleo.
Como a API REST do WordPress agora é parte integrante do núcleo do WordPress, é importante que os desenvolvedores entendam bem como ela funciona e as novas possibilidades que ela abre para interagir com o WordPress.
E assim, nesta visão geral e tutorial da API REST do WordPress, vou orientá-lo no básico da API REST do WP, bem como mostrar como você pode usá-la para criar um widget (plugin) que exibe as postagens mais recentes do Heroic Knowledge Tipos de postagem personalizados básicos.
Uma cartilha sobre a API REST do WordPress
Antes de vermos como usar a API REST do WordPress para criar um widget (plugin), vamos primeiro entender um pouco melhor o termo.
Então, o que significa API?
API significa Interface de Programação de Aplicativos .
Em termos mais simples, é um meio de comunicação entre dois aplicativos diferentes.
Um exemplo comum de uma API em ação é o Tweet Deck que muitos sites exibem. A exibição deste Tweet Deck torna-se possível por meio de uma API onde o site apenas extrai dados do Twitter e os exibe.
E o RESTO?
REST é a abreviação de REpresentational State Transfer .
REST é um estilo de arquitetura baseado em HTML de construção de APIs. Uma arquitetura RESTful usa solicitações HTTP para postar, ler, atualizar e excluir dados entre duas fontes.
Então, quando falamos de uma API REST, queremos dizer essencialmente uma API que usa métodos HTML para se comunicar.
E o JSON?
A API REST do WordPress tem o mesmo formato da API REST JSON do WordPress.
JSON (ou Javascript Object Notation ) é um formato mínimo de intercâmbio de dados baseado em texto que é usado para trocar dados entre plataformas diferentes (mesmo que as plataformas usem idiomas diferentes).
JSON é uma alternativa leve para soluções baseadas em XML, tornando-o perfeito para aplicativos móveis com limitações de largura de banda.
Por que usar a API REST do WordPress
Você pode estar se perguntando o que há de tão excepcional na API REST do WordPress e por que você deve se preocupar com ela.
Bem… a API REST do WordPress permite que você faça mais com o WordPress.
Por exemplo:
- Escreva aplicativos em qualquer idioma que você conheça e faça com que ele interaja com um site WordPress (os únicos 2 requisitos são que o idioma do seu aplicativo deve usar métodos HTML e ser capaz de interpretar JSON)
- Crie experiências de administração e conteúdo totalmente personalizadas
- Desenvolva aplicativos de página única em cima do WordPress
E muito mais.
É quase impossível listar todos os aplicativos/interfaces/experiências potenciais que podem ser criados com a API REST. O manual da API REST do WordPress diz com razão:
Nossa imaginação é o único limite para o que pode ser feito com a API REST do WordPress. A conclusão é que, se você deseja uma maneira estruturada, extensível e simples de obter dados de entrada e saída do WordPress por HTTP, provavelmente deseja usar a API REST.
Mas eu sei que a implementação é sempre muito mais difícil do que entender a teoria.
Então, vamos ver um tutorial rápido sobre como você pode usar a API REST do WordPress para criar um widget personalizado (plugin).
Um tutorial rápido sobre como usar a API REST do WordPress
Se você tiver um de nossos produtos de base de conhecimento, como nosso tema da Central de ajuda KnowAll ou o seu próprio tema com o plug-in Heroic Knowledge Base, você terá um site com uma base de conhecimento de artigos de suporte. O uso desses produtos não é necessário para seguir os princípios deste tutorial, no entanto, lembre-se de que você precisará adaptar qualquer código à sua própria configuração.
Então, pronto com sua configuração local?
Excelente!
Agora o que vamos fazer é criar outro site em um servidor diferente.
Então, por que estamos criando este segundo site?
Estamos fazendo isso porque queremos implementar a API REST do WordPress para se comunicar com este segundo site e, como você já sabe, a API REST do WordPress tem tudo a ver com fazer as conversas acontecerem.
Então, vamos usar a API REST do WordPress para fazer com que os dois sites conversem entre si e troquem dados.
E o objetivo final do tutorial é:
Escolha os artigos mais recentes da base de conhecimento publicados no site da Central de Ajuda e exiba-os em um widget na barra lateral do novo site.
Para este artigo, o site da Central de Ajuda que contém todos os artigos da base de conhecimento será chamado de site ' local ' e o novo site onde você exibirá o widget será o site ' externo '.
Neste ponto, suponho que você tenha 1) seu site da central de ajuda 'local' e 2) um novo site 'externo' configurado em um servidor diferente.
E no final do tutorial, teríamos exibido com sucesso uma lista de artigos da base de conhecimento do site 'local' no novo site 'externo' (através da API REST do WordPress) usando um widget personalizado (plugin).
Com isso, estamos prontos para começar:
Passo #1: Comece copiando o seguinte código clichê em um novo arquivo .php e salve-o na pasta de plugins do seu site 'externo'.
Veja o código completo para este tutorial da API REST do WordPress aqui.
/**
* 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' ); } ); Este código cria um widget muito simples que exibirá um título de sua escolha.
Ao adicionar o código no topo do template e salvá-lo no diretório de plugins, nós o criamos como um plugin (em vez de adicionar o código ao arquivo de funções do tema).
É uma coisa pequena, mas criar um widget como um plugin neste estilo permite que você possa ligá-lo e desativá-lo e também reutilizá-lo em outros temas posteriormente, se desejar, sem a necessidade de copiar e colar.
Uma vez instalado e ativado, você terá um novo widget na área Widgets do painel:
Etapa 2: Use a API REST do WordPress para buscar os artigos recentes da base de conhecimento
Como você não deseja editar ou excluir nada neste desenvolvimento, vamos nos concentrar apenas na função widget(). É aqui que o conteúdo do widget é enviado para o site 'externo'.
Para 'obter' a lista dos artigos recentes da base de conhecimento do site 'local', há algumas coisas que precisamos saber:
- O caminho base da API (qual API usar em seu site, no nosso caso, a API WP mais recente)
- A rota usada (API WP tem várias rotas para os diferentes conjuntos de dados e operações disponíveis)
- O endpoint usado (Qual ação deve ser executada)
- Parâmetros (os dados associados à solicitação)
O caminho base da API é sempre:
json/wp/v2/
E assim o caminho absoluto da API se torna:
http://example.com/json/wp/v2/
(http://example.com é o seu site 'local')
A rota utilizada é:
json/wp/v2/posts/
Sobre os endpoints: Esta rota na verdade tem três endpoints que são diferenciados pelos métodos HTTP. Esses terminais são:
- PEGUE
- COLOCAR
- EXCLUIR
Neste exemplo, você escolherá o ponto de extremidade GET para que possa recuperar (ou 'obter') uma lista de postagens mais recentes do site 'local'.
Portanto, sua primeira linha de código interagindo com a API REST será:
$response = wp_remote_get( 'http://products-website.com/wp-json/wp/v2/posts/' );
Em seguida, você precisa verificar se algum erro é retornado:
if( is_wp_error( $response ) ) {
return;
}
Tudo o que esse código faz é verificar qual resposta é retornada. Se a resposta retornar algumas postagens, não há erro.
A última parte desta seção é:
$posts = json_decode( wp_remote_retrieve_body( $response ) );
if( empty( $posts ) ) {
return;
}
$response é uma string codificada em JSON com dados Post. Então tudo o que você está fazendo aqui é decodificá-lo para que possa ser gerado.
Novamente, adicione uma verificação adicional para garantir que $posts não esteja vazio. Se for, então nada é retornado.
Portanto, neste ponto, você se comunicou com sucesso com seu site 'local' usando a API. Essa implementação deixa você com uma lista de postagens a serem exibidas.
A próxima etapa é realmente exibi-los em seu widget no site 'externo'.
Etapa 3: exiba as postagens mais recentes no site 'externo' adicionando o seguinte código:
if( !empty( $posts ) ) {
echo '<ul>';
foreach( $posts as $post ) {
echo '<li><a href="' . $post->link. '">' . $post->title->rendered . '</a></li>';
}
echo '</ul>';
}O código do seu widget concluído deve ficar assim:
/**
* 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' ); } ); Com a etapa acima concluída, quando você tentar visualizar seu site 'externo', verá uma lista de suas postagens do site 'local' na barra lateral.
Isso tudo é ótimo.
No entanto, se você se lembra, essas não são as postagens certas porque queremos mostrar apenas os artigos mais recentes da Base de Conhecimento.
Nossa implementação atual não faz isso porque o plug-in da Base de Conhecimento usa seu próprio tipo de postagem personalizado. E como os tipos de postagem personalizados não estão publicamente disponíveis para APIs por padrão, isso causa um problema. (Observação: a versão mais recente da base de conhecimento está disponível publicamente para a API REST e a próxima seção pode ser ignorada)
Usando a API REST com tipos de postagem personalizados
Para disponibilizar tipos de postagem personalizados para a API REST, você precisa de uma pequena solução alternativa.
Portanto, ao criar um tipo de postagem personalizado, você precisa adicionar um novo parâmetro para registrar os argumentos do tipo de postagem para disponibilizá-lo publicamente:
'show_in_rest' = true, 'rest_base' = 'ht_kb', 'rest_controller_class' = 'WP_REST_Posts_Controller',
Mas, como no nosso caso, estamos usando um plug-in para ativar o tipo de postagem do artigo da base de conhecimento, não editaremos diretamente o arquivo do plug-in para disponibilizar os tipos de postagem personalizados para a API REST. (Editar um arquivo de plugin diretamente nunca é uma boa ideia!)
O que faremos é adicionar o seguinte código ao arquivo functions.php no tema filho do site 'local':
/**
* 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';
}
}Agora, o tipo de postagem personalizado 'ht_kb' está disponível publicamente para a API REST do WP.
Depois de disponibilizar o tipo de postagem personalizado para a API REST do WordPress, agora precisamos corrigir nosso widget para mostrar postagens com esse tipo de postagem. Para isso, voltaremos ao código $response da Etapa 2 e o atualizaremos para:
$response = wp_remote_get( 'http://example.com/wp-json/wp/v2/ht_kb/' );
Estamos basicamente alterando /posts/ para /ht_kb/ na rota da API porque 'ht_kb' é o nome do tipo de postagem personalizado do plug-in.
Depois de atualizar seu widget e visualizar o site 'externo', você deverá ver os artigos mais recentes da Base de conhecimento.
Pensamentos finais
Bem, como vimos, usando alguns fragmentos simples de PHP e HTML, você pode criar novas funções, widgets e plugins.
Você pode alterar o plug-in que acabamos de criar para criar uma caixa de pesquisa que usa a API REST do WP para pesquisar os artigos da Base de conhecimento e retornar os resultados no widget.
Ou você pode usar a autenticação para controlar quem vê os resultados (útil se você criou conteúdo restrito).
Há tanta coisa que você pode tentar! Basta acertar o básico, e você estará pronto.
Leitura adicional
Há muito conteúdo obsoleto em torno da API REST do WordPress, portanto, certifique-se de ler o material atualizado. Eu linkei alguns recursos úteis em todo o post, mas estou listando alguns aqui também.
Portanto, leia-os e descubra as diferentes maneiras criativas de usar a API REST.
- Manual da API REST
- Perguntas frequentes sobre a API REST
- WP REST API: é para onde estamos indo?
Se você tiver alguma dúvida sobre a implementação da API REST do WordPress, deixe-a nos comentários abaixo!