O Guia Completo do WordPress REST API Basics

A API do WordPress REST 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ê não tiver trabalhado com o WordPress REST API, você pode estar querendo saber exatamente o que é. Então vamos começar por olhar para o que é a API REST.

O que é a API do WordPress REST?

A API do WordPress REST é 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 Aplicações (API)?

Uma Interface de Programação de Aplicação, 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 atalhos. 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 atalhos 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 a parte 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. Os URLs usados 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. As aplicações clientes e as aplicações de servidor devem ser separadas, para que possam ser desenvolvidas independentemente umas das outras. Se a tecnologia do lado do servidor (ou seja, o WordPress) for alterada, a aplicação do lado do servidor (uma aplicação, por exemplo) deve continuar a poder aceder-lhe através do mesmo método simples.
3. Sem pátria. 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. Cacheable. 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 do WordPress REST é um conjunto de código projetado para tornar possível 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 do WordPress REST

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

Fundo para a API do WordPress REST

A API do WordPress REST 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 aplicações 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 aplicações 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 do 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 na aplicação móvel WordPress.
• Self-hosted WordPress admin telas olhando mais como WordPress.com telas 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 metacaixas nos ecrãs de página e pós edição.

Com o tempo, a API do WordPress REST 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 do WordPress REST

Como você acessa a API do WordPress REST?

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.

Vamos ver como começas.

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 idéia experimentar com a API REST em um site de teste local antes de tentar em um site ao vivo.

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 ao vivo, 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 posts que foram publicados, você poderia usar:

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

Isto iria buscar todos os posts publicados porque são públicos.

Visão geral dos comandos da API do WordPress REST

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 post ou outros dados.
• O POST adiciona um recurso ao servidor, como um posto, 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 dar uma vista de olhos em cada um destes.

GET

O commando GET command é 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.

Digamos que querias ir buscar o último post. Tu usarias isto:

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 posts. Consulte o Manual da API do WordPress REST 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 post, 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 post usando um comando PUT para editá-lo.

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

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 posts.

Digamos que você tem uma série de posts 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 post 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 post 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.

Por isso, se quisesses mover o post que acabaste de criar para o lixo, usavas isto:

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 do WordPress REST

A API do WordPress REST 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 seu aplicativo vai ser usado em dispositivos que não executam JavaScript ou por usuários que são susceptíveis de tê-lo desligado, então ele não será executado 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á.

Da mesma forma, se seus usuários são susceptíveis de desligar o JavaScript, então trabalhar com a API REST irá causar problemas. Alguns usuários desativam o JavaScript em seus navegadores por razõ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.

Isto deve-se em grande parte à forma como o JavaScript é utilizado para fornecer conteúdos dinâmicos que podem não funcionar bem com os leitores de ecrã e podem causar problemas a 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 motores de busca.

Google e outros motores de busca 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 do WordPress REST

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 ficheiro 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 irá desativar completamente a API REST para o seu site. Ele pode ter efeitos de knock-on para suas telas de administração, então certifique-se de que tudo funciona bem depois de adicioná-lo.

Aplicações do mundo real usando a API do WordPress REST

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 do WordPress REST 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)

Também nos ecrãs de administração do WordPress, mas desta vez também no WordPress auto-hospedado, o editor de blocos do Gutenberg faz uso da API REST para comunicar com a sua base 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 que os usuários possam acessar dados a partir dela de fora do WordPress. Isso significa que você pode criar aplicativos 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 front-end construído usando o React com um backend alimentado pelo WordPress (sugestão de leitura: O seu 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 do WordPress REST 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 online para sua seção de esportes, construído com JavaScript.

Resumo

A API do WordPress REST 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.

Qual é a sua opinião sobre a API REST? Já o usou para alguns dos seus projetos? Diga-nos na seção de comentários abaixo!