Introdução ao WP REST API

Com a sua criação em 2003, o Wodpress cresceu a partir de uma plataforma de blog para um completo sistema de gerenciamento de conteúdo. Nos ultimos anos, está maduro o suficiente para atender as demandas da internet, e por essa razão hoje o WordPress é utilizado por mais de 25% da web.

Com tantos recursos sendo integrados ao WordPress, um dos ultimos adicionados foi a Rest API que permite que outras aplicações e plataformas se comuniquem com o WordPress. Foi uma atualização revolucionária que permite aos desenvolvedores criar aplicações customizadas e sistemas integrados com o WordPress. Como a API tem a capacidade de socilitar e adicionar conteúdo de qualquer cliente ou site, sem precisar ter o WordPress instalado naquele host, permite que o WordPress possa ser utilizado com qualquer linguagem ou plataforma.

Nesta serie vamos analisar a Rest API do WordPress e como podemos utiliza-la para criar recursos, que seriam impossíveis ou bem complicados utilizando apenas o WordPress. Primeiro vamos dar uma olhada nos conceitos, incluindo Rest e JSON, depois vamos explorar as opções disponíveis para nós na WP Rest API.

Abaixo tem alguns conteúdos que achei interessante sobre os conceitos básicos de HTTP, Rest e JSON. Recomendo que dê uma olhada nos links caso não tenha conhecimento dos termos:

• A Beginner’s Guide to HTTP and REST por Ludovico Fischer
• Demystifying REST por Jeffrey Way
• Introducing JSON por Michael James Williams
• Storing Data with JSON (vídeos) por Andrew Burgess

Antes de começar, vamos pensar na arquitetura REST e tentar nos familiarizar com sua terminologia.

Introdução ao REST

Para começar este tópico, vamos analisar a arquitetura REST (Representational State Transfer) e alguns dos seus conceitos básicos. Entender o básico é essencial para quem deseja desenvolver aplicações utilizando algum serviço REST ou sua arquitetura.

REST é um tipo de arquitetura que ajuda a criar e organizar sistemas distribuídos. Ela descreve a web como uma aplicação distribuída de hypermedia que se comunicam trocando representações de estados dos recursos.

Recursos são as principais partes de uma arquitetura REST. Na verdade, eles também podem ser considerados na arquitetura inicial da web, já que a web é orientada a recursos.

Quando falamos sobre WordPress, esses recursos podem ser entidades como posts, páginas, comentários, usuários, custom post types e etc. Para interagir com os recursos, utilizamos URIs (indentificador unico de recurso), que como o nome sugere, é um identificador de recursos.

Um serviço RESTful utiliza as URIs como principal meio para utilizar um recurso. Esse recurso pode ter diversas representações. Por exemplo, um arquivo de imagem pode estar no formato .JPG, .GIF, ou .PNG. Essa relação entre recursos e URIs é uma relação de um-para-muitos. Uma URI pode apontar apenas para um unico recurso, mas um recurso pode ter mais de uma URIs.

Abaixo a lista de todos os recursos disponíveis na WP REST API:

• Posts
• Páginas
• Mídia
• Custom Post Types
• Post Meta
• Revisões
• Comentários
• Termos
• Usuários

Podemos executar diferentes ações nestes recursos utilizando verbos HTTP.

Verbos HTTP

Uma API REST basicamente permite executar ações CRUD (criar, ler, atualizar e deletar) nos recursos utilizando HTTP. Por isso, a arquitetura REST faz uso de um conjunto limitado de requisições HTTP.

1. GET: utilizado para ler ou requisitar um recurso.
2. POST: utilizado para criar um novo recurso
3. PUT: utilizado para atualizar um recurso.
4. DELETE: utilizado para deletar um recurso
5. HEAD: utilizado para verificar se um recurso existe, sem retornar sua representação.
6. OPTIONS: utilizado para requisitar todos os verbos suportados por um recurso.

Em um serviço RESTful, esses verbos tem funções bem definidas. Os primeiros quatro verbos na lista, fazendo parte das ações CRUD, eles requisitam, criam, atualizam e deletam entidades. Os últimos dois verbos auxiliam na verificação da existência de recursos e quais ações HTTP estão disponíveis para eles.

Uma requisição GET retorna informação e é idempotente, ou seja, um cliente pode solicitar o recurso diversas vezes mas nunca vai alterar o estado do recurso.

Para requisitar todos os posts utilizando a WP REST API, podemos utilizar o seguinte endpoint:

1

GET wp/v2/posts

O endpoint acima vai retornar a coleção de todas as entidades post.

Quando o seguinte endpoint é utilizado, este deve retornar uma entidade, ou seja, um post de id igual a 100.

1

GET wp/v2/posts/100

Uma requisição POST cria uma nova entidade, e uma requisição PUT atualiza uma entidade.

A seguinte requisição POST pode ser utilizada para criar um novo post (encaminhando o body, vamos abordar essa parte durante a série de posts) com a WP REST API.

1

POST wp/v2/posts

E a seguinte requisição PUT vai atualizar um post de id igual a 100:

1

PUT wp/v2/posts/100

A requisição DELETE apaga um recurso do sistema. Esse tipo de requisição, junto com a requisição PUT, são requisição que se repetem, o que significa que estes métodos tem o mesmo efeito no sistema.  Por exemplo, se você utilizar uma requisição PUT diversas vezes em um recurso (com os mesmos argumentos), o resultado vai ser sempre o mesmo. O mesmo acontece para a requisição DELETE. Deletar um recurso diversas vezes vai ter sempre o mesmo efeito, ou seja, o recurso vai ser apagado (ou um erro deve ser retornado caso o mesmo já tenha sido deletado).

Junto com essas operações CRUD, um serviço RESTful também disponibiliza mais dois verbos, que são o OPTIONS e o HEAD. Esses verbos são úteis para verificar que recursos estão disponíveis em um sistema, e que ações ele suporta, o que servir como uma documentação para o cliente explorar o sistema. Vamos ver esses dois métodos em ação durante o tutorial.

Mais sobre Routes e Endpoints

Note que no primeiro exemplo, utilizamos o seguinte endpoint:

1

GET wp/v2/posts

Endpoints são funções que a API disponibiliza para executar ações como retornar posts (foi o que fizemos), criar um novo usuário, ou atualizar um post meta. Também podemos dizer que um endpoint executa um método com função específica.  Esses endpoints são dependentes do verbo HTTP associado a eles. No exemplo acima, utilizamos o verbo GET para requisitar todos os posts.

A route (ou rota) do endpoint acima é a seguinte:

1

wp/v2/posts

A route basicamente é o nome (ou caminho) de acesso ao endpoint. Uma route pode ter diversos endpoints baseados em verbos HTTP. A route abaixo tem o seguinte endpoint para criar um novo post:

1

POST wp/v2/posts

Este endpoint, quando executado com parametros, deve criar uma nova entidade post.

Considere a seguinte route:

1

wp/v2/posts/100

Essa route aponta para a entidade Post com id igual a 100. Nela podemos utilizar os seguinte endpoints:

1. GET wp/v2/posts/100: que pode ser utilizado para requisitar o post de id 100. Essa requisição executa o método get_item().
2. PUT wp/v2/posts/100: pode ser utilizado para atualizar um post de id 100. Este executa o método update_item().
3. DELETE wp/v2/posts/100: este deleta um post de id 100. E executa o método delete_item().

Vamos aprender mais sobre a estrutura intera da WP REST API, sua estrutura de classes e métodos interno, na parte final da série.

Vamos refrescar nossa mente com algumas repostas padrões do HTTP e o que elas significam.

Repostas HTTP

Um servidor responde uma requisição retornando um código de status HTTP. Esses códigos são números com significado pré definido.  Por exemplo, qualquer um utilizando a internet já está familiarizado com o código 404, que indica que o recurso requisitado não foi encontrado.

A resposta do servidor também depende do tipo de verbo HTTP ou método que foi utilizado na requisição.

A seguir temos alguns códigos de resposta HTTP, junto com o significado, e que vamos encontrar enquanto trabalhamos com a WP REST API:

• 200 - OK: significa que a requisição foi completada com sucesso e o servidor retorno uma resposta. Normalmente temos este retorno quando efetuamos uma requisição GET com sucesso.
• 201 - Created: normalmente é o retorno de uma requisição POST com sucesso. Indica que o recurso foi criado.
• 400 - Bad Request: resposta do servidor quando uma requisição é encaminhada com parâmetros inválidos. Normalmente é o retorno de requisições PUT ou POST.
• 401 - Unauthorized: significa que um usuário não foi autorizado a executar determinada ação. Por exemplo, um usuário tentou criar ou deletar um recurso sem fazer autenticação.
• 403 - Forbidden: significa que o servidor entendeu a requisição mas recusou de acordo com a autenticação. Isso acontece quando um usuário efetua autenticação mas não tem os privilégios necessários para a executar a ação.
• 404 - Not Found: o código mais conhecido. Indica que um recurso, que o usuário estava procurando, não foi encontrado.
• 405 - Method not Allowed: significa que o verbo HTTP utilizado na requisição não é suportado pelo recurso. Um exemplo pode ser um usuário tentando atualizar um recurso que permite apenas a leitura.
• 410 - Gone: indica que um recurso foi movido de uma local para outro. Um exemplo pode ser tentar deletar um recurso que já havia sido deletado.
• 500 - Internal Server Error: é o retorno dado pelo servidor quando este encontra uma condição inesperada e não consegue completar a requisição.
• 501 - Not Implemented: significa que o servidor não suporta a ação utilizada para completar a requisição. Geralmente ocorre quando um servidor recebe uma requisição que não é reconhecida.

Vamos analisar esses verbos HTTP e respostas mais de perto quando começarmos a trabalhar com a API. Mas antes, vamos dar uma olhada nas razões para se utilizar uma REST API com o WordPress e as vantagens tanto para o usuário quanto para o desenvolvedor. Portanto, preciso que você realmente esteja interessado em acompanhar a série.

Por que utilizar uma REST API JSON com o WordPress?

O REST e JSON juntos fornecem um mecanismo poderoso para criar aplicações utilizando o back-end do WordPress. O melhor exemplo pode ser aplicações mobile que efetuam troca de informações entre o cliente (dispositivo) e o servidor. Tendo em mente as limitações de banda quando utilizamos celular, o JSON é uma boa alternativa às soluções baseadas no XML.

Como o JSON é uma forma de armazenar informações em texto, ele pode ser utilizado com a maioria das linguagens de programação. Além disso, o JSON fornece uma conexão padrão quando troca informações em diferentes plataformas, e que pode ser compreensível tanto para humanos quanto para máquinas.

Utilizando uma API, como essa que estamos discutindo no artigo, seu conteúdo não está limitado apenas ao WordPress, mas a qualquer site ou cliente. Como uma API expões partes do seu funcionamento interno, clientes remotos podem interagir com o site atualizando ou crinado novos conteúdos. Isso também permite requisitar conteúdo em um site WordPress e apresentar em outro.

Com a ascensão de frameworks JavaScript como o Angular, Backbone ou Ember, agora é possível criar boas experiências para o usuário utilizando o back-end do WordPress.

Dito isso, vejamos alguns casos interessantes para utilizar a WP REST API:

• Aplicativos mobile
• Paineis administrativos customizados para o Wordpress
• Single Page Applications ou Aplicações de página única (SPAs)
• Integração com outras plataformas (como Ruby, .NET e Django, além de outras).
• e muito mais...

A API realmente abre um modo de possibilidades, onde o limite é a imaginação do desenvolvedor.

Uma breve história da API REST JSON no WordPress

Antes da API REST baseada em JSON, a API utilizado para interagir com o WordPress era a XML-RPC API, que ainda tem suporte no core do WordPress. O problema com o XML é que ele não é tão leve quanto o JSON e não tão fácil de manipular. Manipular um XML pode ser uma dor de cabeça, enquanto manipular um objeto JSON é tão simples quanto manipular um objeto JavaScript.

A primeira REST API introduzida no WordPress foi a API JSON, lançada em 2009. Foi criada no The Museum of Modern Art para o blog Inside/Out. O front do blog utilizava Ruby on Rails, então para requisitar posts e adicionar comentários no back-end do WordPress, foi criada uma API. Esse plugin fornece uma interface para requisitar conteúdo e atualizar comentários no back-end do WordPress. Esse plugin não é atualizado a mais de dois anos, mas continua presente no repositório oficial e pode ser utilizado.

Além do plugin API JSON, o WordPress.com também tem fornece uma API JSON atráves do plugin JetPack.

A WP REST API, como conhecemos hoje, é um plugin proposto por Ryab McCue como parte do GsoC (Google Summer of Code) 2013. Ainda está para ser incluída no core do WordPress em uma versão futura (no momento em que este post foi traduzido, a API já havia sido introduzida no core, na versão 4.7 do WordPress). A versão atual do plugin é 2.0 e está em estado beta, parcialmente integrada no core do WordPress 4.4. É um projeto da comunidade, liderado por Ryan McCue e Rachel Baker. O repositório oficial do plugin está no GitHub, e a documentação oficial pode ser encontrada neste site.

Atual estado da WP REST API

Como mencionado, a WP REST API atualmente é um plugin e tem atividades bem ativas no GitHub. Foi parcialmente inclusa no core do WordPress 4.4 e o Ryan apresentou seu plano para incluir ela no WordPress.org.

De acordo com a proposta, a WP REST API deve ser incorporada no core do WP em dois estágios:

Código de infraestrutura

De acordo com a proposta, no estágio inicial, apenas o código ligado a infraestrutura seria incluso no core do WP na versão 4.4. Essa atual estrutura de código é a base da WP REST API, já que inclui a serialização e deserialização do JSON, linkin, embedding, e o mais importante de tudo -  a rota que faz a API operar. O código não inclui os endpoints e a classes de controle, mas fornece uma base para criar APIs dentro do WordPress.

Enquanto escrevo o artigo, este estado já foi incluso no core do WordPress 4.4.

Integração dos Endpoints

O endpoint para posts, páginas, usuários e taxonomias e etc serão incorporados no core da versão 4.5 do WP, um release depois de incorporar o código de infraestrutura. Os endpoints são o que fazem a API útil para a maioria dos clientes. Eles são bem complexos, incluindo mapeamento de informações externas em formato JSON para o formato nativo do WP, e vice versa. Correspondem dois terços do código da API, com aproximadamente 5500 linhas.

A estratégia aqui é criar confiança de desenvolvimento na API fornecendo o código no core. Isso permitiria desenvolvedores de temas e plugins utilizarem suas próprias APIs. Mas até então, endpoints não vão ser inclusos neste estágio, e isso pode limitar a utitilidade inicial da API.

O gap entre dois lançamentos pode dar o tempo que o time do WP core precisa para revisar os endpoints da API.

Outra vantagem que WP REST API trouxe para a comunidade do WordPress foi a utilização do GitHub para controle de versão do projeto. Todas as contribuições do WordPress eram feitas pelo SVN ou Trac, e o time da WP REST API está bem confiante quanto a utilização do GitHub.

Após a atualização da API direto no core, podemos esperar o desenvolvimento acelerado de outras áreas como por exemplo a autenticação OAuth 1.0a.

Ferramental

Para começar a testar a API REST do WP, precisamos de um cliente HTTP que será usado para fazer requisições ao servidor e visualizar a resposta. É questão de gosto, mas usaremos aqui o Postman, para Google Chrome, durante a série. Alternativas ao Postman são:

• REST Easy para Firefox
• httpie para linha de comando

Postman nos permite criar requisições HTTP rápidas para diferentes métodos, visualizar a resposta do servidor e testar configuração para autenticação. Todos esses recursos serão extremamente úteis ao trabalhar com a API REST do WP.

Precisamos agora é ter o WP-CLI no nosso servidor. Com o WP-CLI, podemos administrar, remotamente, nossa instalação WordPress pela linha de comando sem precisar abrir um navegador. Precisaremos usar o WP-CLI na próxima parte da ´serie ao configurar a autenticação OAuth 1.0a. Encontramos a instrução de instalação no site oficial.

Além de um cliente HTTP e do WP-CLI, também precisamos de dados demo na instalação WordPress. Sugerimos o Theme Unit Test (XML) ou o plugin Demo Data Creator, que permite criar vários posts, páginas e usuários.

Instalando o Plugin

No momento da publicação desse artigo, a versão estável atual é a 1.2.2 que encontramos no repositório oficial. Nessa série, trabalharemos com a versão 2.0 já que foi re-escrita do zero e contém mudanças radicais. Podemos buscar a versão beta da 2 na página oficial do plugin ou do repositório no GitHub.

Notemos que não é recomendável instalar a versão beta em ambiente de produção. Configuramos um ambiente WordPress local, logo, recomendamos fazer o mesmo, para testes.

Para instalar o plugin do repositório do GitHub, abramos o terminal e baixemos direto na pasta /wp-content/plugins:

1

$ git pull https://github.com/WP-API/WP-API.git

O plugin será baixado na sub-pasta /WP-API/.

Podemos ativá-lo pelo admin do WordPress para continuar a testá-lo.

Para o plugin da API REST do WP funcionar, precisamos habilitar Links Permanentes Legíveis no WordPress. Assume-se que já é sabido como fazer isso. Caso contrário, o WordPress.org ajudará.

Avaliando a Disponibilidade da API

Após o plugin ser instalado, podemos avaliar a disponibilidade da API no servidor. Não nos limitamos ao uso da API ao nosso site. Na verdade, podemos usá-la em qualquer site que a tiver instalá-la e habilitada. Para verificar a API em outros sites, podemos enviar requisições HEAD para o site, dessa forma:

1

$ HEAD http://someothersite.com/

Isso retornará o cabeçalho de resposta a seguir:

O cabeçalho Link aponta para a rota raiz da API do WP que, em nosso caso, é a seguinte:

1

http://localserver/wordpress-api/wp-json/

A API também pode ser descoberta através de JavaScript (ou jQuery) no navegador, selecionando o elemento <link> apropriado na DOM, assim:

1

(function( $ ) {

2

    var $link = $( 'link[rel="https://github.com/WP-API/WP-API"]' );

3

  var api_root = $link.attr( 'href' );

4

})( jQuery );

Daqui, podemos começar a buscar o conteúdo do site através da API REST do WP. Notemos que apenas requisições autenticadas podem editar ou atualizar o conteúdo no site e deixaremos isso para as próximas duas partes da série.

O Que Vem Depois?

Nessa parte introdutória da série, aprendemos muito sobre a arquitetura REST, a API REST do WP e sobre HTTP. Primeiro vimos os conceitos básico da arquitetura REST e como ela ajuda desenvolvedores a criar aplicações melhores. Depois aprendemos sobre HTTP, seus verbos e tipos de respostas. Também vimos histórico curto sobre APIs no WordPress e como a API REST é diferente dos antecessores.

Na parte final do tutoria, instalamos o plugin direto do GitHub. Depois, familiarizamo-nos com requisições HEAD que podem ser usadas para verificar a disponibilidade da API no nosso servidor e em servidores de terceiros.

Com o ambiente base configurado, estamos prontos para trabalhar com os recursos que a API REST provê. Na próxima parte, veremos formas de configurar métodos de autenticação suportados pela API. Esse métodos serão obrigatório ao enviar requisições para buscar, criar, atualizar e apagar conteúdo. Fiquemos de olho.