O Guia Completo da API REST do WordPress

A API REST do WordPress está em processo de modificação do WordPress. Você pode não ter notado, como um monte dele está sob o capô, mas as implicações da API REST fazem uma enorme diferença para o futuro do WordPress, tanto em termos de sua base de código e seus usos.

Se você ainda não teve experiência com a API REST do WordPress, talvez esteja se perguntando o que ela é. Então, vamos começar entendendo o que é API REST.

O que é API REST do WordPress?

A API REST do WordPress é uma interface que os desenvolvedores podem usar para acessar o WordPress de fora da própria instalação do WordPress. Você acessa-o usando JavaScript, o que significa que ele pode ser usado para criar sites e aplicativos interativos.

REST significa Representational State Transfer e API significa Application Programming Interface. Vamos ver o que cada um deles significa.

O que é uma Interface de Programação de Aplicativos (API)?

Uma Interface de Programação de Aplicativo, ou API, é definida como:

“Uma interface ou protocolo de comunicação entre um cliente e um servidor para simplificar a criação de software do lado do cliente.”

Se você não está familiarizado com APIs, isso pode não ajudar muito. Em termos mais simples, uma API é um conjunto de código que permite que um sistema interaja (ou “interface”) com outro. Se alguma vez adicionou um mapa do Google ao seu site WordPress, utilizou a API do Google Maps, que permite ao seu site WordPress interagir com o Google Maps.

Estes sistemas não precisam de ser completamente separados. O WordPress já possui várias APIs, para coisas como plugins, configurações e shortcodes. Estes podem ser usados por desenvolvedores de plugins e temas para interagir com o núcleo do WordPress e fazer as coisas acontecerem (como criar shortcodes e adicionar telas de configurações ao administrador do WordPress).

A diferença com a API REST é que ela permite que sistemas fora da sua própria instalação do WordPress interajam com o WordPress, que é onde o REST entra.

O que é a Transferência Estadual Representacional (REST)?

A Transferência de Estado Representacional, ou REST, fornece padrões que os sistemas web podem usar para interagir entre si. Sem o REST, dois sistemas não seriam capazes de se entenderem uns aos outros e assim enviar dados para trás e para frente.

Para que uma solicitação seja RESTful, ela deve estar em conformidade com cinco princípios:

1. Interface uniforme. As URLs usadas para acessar recursos no sistema devem ser uniformes, consistentes e acessíveis através de uma abordagem comum, como o GET (mais dos quais em breve).
2. Cliente-servidor. Aplicativos cliente e aplicativos servidor devem ser separados, permitindo que sejam desenvolvidos independentemente um do outro. Se a tecnologia do lado do servidor (como o WordPress, por exemplo) mudar, o aplicativo do lado do servidor ainda deve ser capaz de acessá-la pelo mesmo método simples.
3. Sem estado. O servidor não muda de estado quando uma nova requisição é feita usando a API. Não armazena os pedidos que foram feitos.
4. Cacheável. Todos os recursos devem ser cacheáveis, para melhorar a velocidade e a conformidade com os padrões da web. O cache pode ser implementado no servidor ou no lado do cliente.
5. Sistema em camadas. Um sistema RESTful permite que você use várias camadas para acessá-lo, armazenando dados em servidores intermediários se necessário. O servidor não pode dizer se o cliente final está diretamente conectado a ele.

Todas essas restrições estão relacionadas a páginas da Web e aplicativos e regem a forma como um aplicativo pode interagir com a API.

O que isso significa para o WordPress?

Colocar REST e API juntos significa que a API REST do WordPress é um conjunto de código projetado para permitir que outros sistemas tenham interface com o WordPress e que é construído de forma a garantir que esses sistemas se entendam.

Isso significa que um site de terceiros ou um aplicativo móvel, por exemplo, pode acessar seu banco de dados do WordPress, obter dados dele e adicionar dados a ele.

No entanto, há uma série de implicações e usos para isso.

Entendendo a API REST do WordPress

A API REST do WordPress foi desenvolvida em resposta a mudanças na forma como sites e aplicativos são desenvolvidos e à necessidade de abrir o WordPress mais amplamente.

Introdução da API REST do WordPress: Da criação ao uso atual

A API REST do WordPress foi lançada como parte do núcleo na versão 4.7 em dezembro de 2016, mas estava por aí como um plugin antes disso.

Ele é projetado para suportar uma gama de aplicativos construídas no WordPress e para transformar o WordPress de um sistema de gerenciamento de conteúdo para uma plataforma de aplicativos.

Ele é usado extensivamente pelo WordPress.com, cuja interface baseada em JavaScript usa a API REST para interagir com o banco de dados do WordPress. Também é usado pela interface de edição do Gutenberg, que se tornou parte do núcleo em 2019.

A API REST amplia a gama de aplicativos para as quais o WordPress pode ser usado. Embora um sistema de gerenciamento de conteúdo seja excelente na execução de um site complexo, uma plataforma de aplicativos também pode ser usada para alimentar aplicativos ou SPAs de página única baseados na Web (se você já usou o Google Docs, usou um deles).

Nestes, o conteúdo é atualizado quando o usuário toma ação, em vez de carregar novas páginas. Como ele usa JavaScript (uma linguagem client-side) ao invés de PHP (uma linguagem server-side), ele pode fazer as coisas acontecerem no navegador do usuário sem ter que constantemente enviar requisições para o servidor.

Implicações para usuários e desenvolvedores WordPress

Se você for um usuário e/ou desenvolvedor trabalhando com o WordPress, a API REST tem várias implicações.

Para os utilizadores, estes incluem:

• Alterações à interface, incluindo o editor do Gutenberg.
• Alterações e melhorias no aplicativo móvel WordPress.
• Telas de administração do WordPress auto-hospedado ficando cada vez mais parecidas com as telas do WordPress.com ao longo do tempo.

Para os desenvolvedores, há implicações e possibilidades mais amplas:

• A capacidade de criar SPAs usando a API REST, puxando dados do WordPress, mas parecendo muito diferente do WordPress.
• A capacidade de integrar o WordPress com outras tecnologias e sistemas de frontend.
• A capacidade de desenvolver com WordPress se você é um desenvolvedor de frontend que não escreve PHP.
• Para desenvolvedores de PHP, uma necessidade crescente de expandir suas habilidades para incluir JavaScript.
• Alterações específicas, tais como a necessidade de construir blocos Gutenberg em vez de metabox nos ecrãs de página e pós-edição.

Com o tempo, a API REST do WordPress significará que mais do núcleo do WordPress será escrito em JavaScript e não em PHP. Se você é um desenvolvedor do WordPress, isso significa que você precisará aprender JavaScript.

Como acessar a API REST do WordPress

Como você acessa a API REST do WordPress?

Para acessar a API WP-REST, você precisará acessar seu site através da linha de comando. Com o WordPress, isto chama-se WP-CLI. Você não faz nada disso através de suas telas de administração ou acessando diretamente o código em seu site.

Acesso ao WP-REST via WP-CLI

WP-CLI é a interface de linha de comando do WordPress. Permite-lhe aceder e trabalhar com o WordPress através da Interface de Linha de Comandos (CLI) no seu computador. WP-CLI é pré-instalado com todos os planos de hospedagem Kinsta.

Para acessar a CLI, abra o Terminal em um Mac ou no Linux, ou o prompt de comando no Windows.

Para acessar um site remoto, você precisa SSH ao seu servidor para acessá-lo via WP-CLI (Não consegue conectar via SSH? Saiba como corrigir o erro “Connection Refused” do SSH).

Para acessar um site local, você simplesmente precisa usar a estrutura de diretório correta a partir da linha de comando. É uma boa ideia experimentar com a API REST em um site de teste local antes de tentar em um site de produção.

Você precisará acessar especificamente a API REST para o seu site, assim:

http://yoursite.com/wp-json/wp/v2

Você pode então adicionar elementos depois disso para acessar certos tipos de dados, que analisaremos com mais detalhes em breve. Estes elementos são chamados de endpoints.

Autenticação

Depois de acessar seu site, você pode precisar passar pela autenticação. Alguns endpoints são públicos e não requerem autenticação, enquanto outros o fazem.

Você não está entrando em seu administrador do site aqui: a API REST faz as coisas um pouco diferente.

Para poder autenticar o seu site através do WP-CLI, terá de instalar um plugin de autenticação. Para instalações de desenvolvimento, o plugin Basic Auth faz o trabalho e é fácil de trabalhar.

No entanto, para sites de produção, você deve usar uma forma mais robusta de autenticação, como o plugin JWT Authentication, que usa JSON Web Token e é mais seguro.

Você pode então usar a linha de comando para acessar dados e incluir autenticação.

O exemplo abaixo usa curve para testar a conexão com o WordPress. Irá emitir uma lista de mensagens de rascunho.

curl -X GET --user username:password -i http://yoursite.com/wp-json/wp/v2/posts?status=draft

As mensagens de rascunho não são informações públicas, então você precisa de autenticação para acessá-las. Mas se você está procurando por dados que são públicos, você não precisa de autenticação. Então, para recuperar uma lista de artigos que foram publicados, você poderia usar:

curl -X GET http://yoursite.com/wp-json/wp/v2/posts

Isso iria buscar todos os artigos publicados porque são públicos.

Visão geral dos comandos da API REST do WordPress

Depois de acessar seu site e saber como usar a autenticação (e se você precisa), você precisará usar um dos vários comandos para interagir com seu site.

Os comandos que você precisa usar são:

• GET recupera um recurso como um artigo ou outros dados.
• O POST adiciona um recurso ao servidor, como um artigo, anexo ou outro recurso.
• O PUT pode ser usado para editar ou atualizar um recurso que já está no servidor.
• DELETE remove um recurso do servidor. Usa-o com cuidado!

Vamos examinar cada um desses tópicos mais de perto.

GET

O comando GET é provavelmente o mais usado: ele recupera dados. O exemplo abaixo (que você usa uma vez que tenha acessado seu site com sucesso) buscaria uma lista de todas as páginas publicadas em seu site:

GET http://yoursite.com/wp-json/wp/v2/posts/?status=published

Note que eu não ter incluído o caminho completo para o seu site na linha acima como você já acessou que usando WP-CLI.

Tendo recuperado esses dados, você pode usá-los para informar sua próxima etapa. Você pode excluir uma dessas mensagens, editá-la ou atualizá-la. Você pode simplesmente enviar mensagens para o seu aplicativo web.

Se você quiser obter o último artigo publicado, você utilizaria o seguinte comando:

GET http://yoursite.com/wp-json/wp/v2/posts/?per_page=1

Há uma série de argumentos que você pode usar ao trabalhar com artigos. Consulte o Manual da API REST do WordPress para mais informações.

POST

Use POST para adicionar novos dados ou recursos ao seu site.

Então, por exemplo, se você quisesse criar um artigo, você começaria usando um comando POST:

POST http://yoursite.com/wp-json/wp/v2/posts/

Isso criaria uma nova mensagem de rascunho vazia.

Você pode então atualizar o artigo usando um comando PUT para editá-lo.

Com um comando POST, você também pode adicionar outros recursos além de artigos, incluindo anexos e outros tipos de artigos.

Para adicionar uma página ao seu site, você pode usar algo assim:

POST http://yoursite.com/wp-json/wp/v2/posts/pages

Isso criaria uma página vazia da mesma forma que você criaria uma mensagem vazia.

PUT

O comando PUT permite editar um recurso existente, incluindo artigos.

Digamos que você tem uma série de artigos no seu site. Você quer verificá-los e atualizar um para torná-lo publicado.

Podias começar por ir buscar uma lista de todas as mensagens do rascunho:

POST http://yoursite.com/wp-json/wp/v2/posts/?status="draft"

O sistema fornecerá uma lista de todas as mensagens de rascunho atuais. É possível modificar o status de um deles usando sua ID:

PUT http://yoursite.com/wp-json/wp/v2/posts/567

Isso acessa esse artigo e permite que você o edite. Em seguida, é possível modificar seu status por meio do argumento de status:

{
"status" = "publish"
}

Ou você pode adicionar conteúdo ao artigo e publicá-lo:

{
"status" = "publish"
"content" = "content here"
}

O servidor retornará um status 200 - OK informando que o pedido PUT foi editado com sucesso.

DELETE

O comando DELETE faz o que você esperaria: ele exclui um recurso. Por padrão, se você usá-lo para excluir uma mensagem, ele irá colocá-lo na lixeira em vez de excluí-lo permanentemente.

Portanto, se você quiser enviar o artigo que acabou de criar para a lixeira, utilizaria o seguinte comando:

DELETE http://yoursite.com/wp-json/wp/v2/posts/567

No entanto, se você quisesse ignorar a lixeira e excluí-la permanentemente, você usaria o argumento de force:

DELETE http://yoursite.com/wp-json/wp/v2/posts/567?force=true

No entanto, se você quisesse ignorar a lixeira e excluí-la permanentemente, você usaria o argumento de força:

Quando não utilizar a API REST do WordPress

A API REST do WordPress nem sempre será a abordagem correta para desenvolver um site ou aplicativo. Aqui estão algumas considerações que você deve estar ciente antes de usá-lo para o desenvolvimento:

Compatibilidade

Se o seu aplicativo for utilizado em dispositivos que não suportam JavaScript, ou por usuários que provavelmente o terão desativado, então o aplicativo não funcionará corretamente se você estiver usando a API REST.

Um site WordPress codificado em PHP irá gerar HTML para que ele não sofra com esse problema. Dispositivos que não usam JavaScript estão ficando mais raros, mas se você estiver desenvolvendo especificamente para aqueles, a API REST não funcionará.

Do mesmo modo, se seus usuários têm tendência a desativar o JavaScript, o uso da API REST pode gerar complicações. Algumas pessoas desativam o JavaScript em seus navegadores por questões de acessibilidade ou segurança.

Acessibilidade

Sites ou aplicativos desenvolvidos usando JavaScript nem sempre são tão acessíveis quanto os resultados em HTML.

Isso acontece principalmente devido à maneira como o JavaScript é usado para criar conteúdos dinâmicos, que podem não ser compatíveis com leitores de tela e podem gerar problemas para pessoas com deficiências visuais ou epilepsia fotossensível.

Usando a API REST para acessar o seu site WordPress e dados de saída em um formulário que é projetado para ser acessível significa que você pode superar esses problemas, mas vale a pena verificar o seu site para a acessibilidade enquanto você está desenvolvendo.

SEO

Aplicativos de página única, que se atualizam com frequência, podem às vezes causar problemas de SEO. Isto é porque o conteúdo que não é entregue quando a página é a primeira saída não pode ser indexado pelos mecanismos de pesquisa.

Google e outros mecanismos de pesquisa estão alcançando com o fato de que muitos sites agora são SPA-powered e estão indexando-os adequadamente. Mas ele paga para fazer uma auditoria de SEO completa de qualquer site que você desenvolver usando a API REST.

Como desativar a API REST do WordPress

Se você não quiser que os aplicativos possam acessar dados do seu site usando a API REST, você pode desativá-la. Lembre-se de que os dados públicos podem ser acessíveis por qualquer pessoa, não apenas você.

Para fazer isso, você pode instalar o plugin Disable WP REST API. Isso desativa a API REST para qualquer um que não esteja conectado ao seu site.

Em alternativa, pode adicionar algum código ao arquivo de funções do seu tema ou escrever o seu próprio plugin. É melhor escrever um plugin já que isso não é uma funcionalidade específica de temas.

No seu plugin, adicione apenas duas linhas:

add_filter( 'json_enabled', '__return_false' );
add_filter( 'json_jsonp_enabled', '__return_false' );

Isso desativará a API REST no seu site por completo. Pode ter impactos secundários nas suas telas de administração, então certifique-se de que tudo está funcionando corretamente depois de fazer essa alteração.

Aplicativos práticos que utilizam a API REST do WordPress

A API REST apresenta algumas possibilidades interessantes para o futuro do WordPress. Aqui estão alguns exemplos de aplicativos e sites que usam a API REST do WordPress para criar SPAs ou vincular o WordPress a outros sites e tecnologias.

WordPress.com

As telas de administração do WordPress.com são construídas inteiramente usando a API REST para fornecer um SPA com o qual os usuários interagem para gerenciar seu site.

Isso possibilita uma comunicação dinâmica entre a interface e o servidor e resulta em uma interface amigável que o WordPress.org provavelmente imitará no tempo.

O Editor de Bloco (Gutenberg)

Nos painéis de administração do WordPress, incluindo versões auto-hospedadas, o editor de blocos Gutenberg também utiliza a API REST para se comunicar com o banco de dados e criar blocos.

Para que os tipos de mensagens funcionem com o editor Gutenberg, devem ter a API REST ativada. O que significa que se estiver a registar um tipo de mensagem personalizada e a utilizar o Gutenberg, terá de adicionar a seguinte linha para ativar o editor de blocos para esse tipo de mensagem:

"show_in_rest" = true;

Event Espresso

Event Espresso é um plugin WordPress que permite aos usuários organizar e divulgar eventos. Ele faz uso da API REST para os usuários poderem acessar dados a partir dela de fora do WordPress. Isso significa que você pode criar aplicativos para dispositivos móveis ou SPAs para gerenciar seus eventos.

UsTwo

UsTwo é uma agência digital cujo site foi construído usando a API REST como um aplicativo de página única. Isso combina um frontend construído usando o React com um backend alimentado por WordPress (sugestão de leitura: Um Guia para Iniciar e Executar uma Agência WordPress Bem-Sucedida).

O conteúdo de uma única página é modular, com uma estrutura diferente de uma página WordPress padrão. Para que isso funcione, eles usam um plugin de construtor de páginas personalizado que permite que sua equipe adicione conteúdo modular ao site.

USA Today

O site da USA Today foi reconstruído usando a integração da API REST do WordPress com os sistemas e módulos existentes no site.

A API REST permitiu que o conteúdo do site fosse enviado para outras lojas, como Facebook Instant Articles e Apple News, usando JSON. Eles também escreveram um jogo social on-line para sua seção de esportes, construído com JavaScript.

Resumo

A API REST do WordPress apresenta alguns desafios interessantes, mas também oportunidades interessantes para usuários e desenvolvedores do WordPress. É o futuro do WordPress e é provável que mude radicalmente a forma como desenvolvemos com o WordPress e a forma como o usamos.

O que você acha da API REST do WordPress? Já utilizou em algum dos seus projetos? Compartilhe sua experiência na área de comentários abaixo!