As APIAS REST estão se tornando cada vez mais populares entre os desenvolvedores e por uma boa razão. Eles fornecem uma interface simples, uniforme e compreensível para serviços de terceiros como Twitter, MailChimp e GitHub.
Com a API do WordPress a caminho (e já disponível através de um plugin ), é o horário nobre para aprender tudo sobre a API HTTP existente no WordPress.
Neste artigo, vou mostrar o que é, como funciona e para o que você pode usá-lo.
Qual é a API HTTP?
Não é de surpreender que a API HTTP seja uma maneira de enviar e receber mensagens usando o HTTP – o idioma da web. Seu navegador envia e recebe mensagens HTTP o tempo todo, como você recebe qualquer página da Web. Através das APIs REST, as mensagens HTTP permitem que você faça coisas mais elaboradas, como atualizar uma postagem, excluir um usuário ou publicar uma nova receita em seu site.
É por isso que a nova API do WordPress é tão importante, que permite o verdadeiro desacoplamento do lado do usuário do seu aplicativo a partir do código principal do WordPress. Para usá-lo, você precisará estar familiarizado com o envio de solicitações HTTP e recebendo respostas, a qual é a API HTTP.
Há muitas maneiras de enviar solicitações HTTP, a API HTTP fornece uma interface unificada usando um punhado de funções auxiliares, o que daremos uma olhada abaixo.
Métodos e recursos HTTP
HTTP é centrado em torno de métodos (às vezes chamados de verbos) e recursos. Os recursos definem o item em que você deseja realizar uma ação específica , o método define o tipo de ação que deseja realizar.
Um recurso é um URL que aponta para um objeto na web, por exemplo, uma publicação. Há uma série de métodos , os mais importantes dos quais são GET, POST, PUT e DELETE.
Você já tem muita experiência com o GET, pois isso é o que você usa para recuperar um recurso. Ao visualizar este artigo, seu navegador fez um pedido GET https://premium.wpmudev.org/blog/using-the-wordpress-http-api/. Os pedidos PUT são usados para modificar recursos, os pedidos POST são usados para criá-los e os pedidos DELETE são usados para excluí-los.
Se o WPMU DEV tivesse uma API REST no lugar, um administrador poderia enviar um pedido DELETE https://premium.wpmudev.org/blog/wordpress-http-api/para destruir um post. Isso pode ser bastante útil para sites grandes com seus próprios aplicativos móveis de gerenciamento.
Uma Solicitação Simples
Vamos enviar um pedido GET simples para testar as águas. Isso pode ser feito usando a wp_remote_get()função, que leva dois parâmetros. O primeiro parâmetro é o URL completo do recurso, o segundo é um conjunto de opções que podemos usar para especificar detalhes.
| $ Test = wp_remote_get (‘http://google.com’); | |
| Eco “< pre >”; | |
| Var_dump ($ test); | |
| Eco “</ pre >”; |
por Isso irá recuperar a página inicial do Google. Se você despeja o valor de $test – qual é a resposta que o Google envia de volta – você deve ver todos os elementos envolvidos.
Os cabeçalhos contêm informações adicionais sobre cada mensagem. Algumas APIs REST solicitarão que você envie informações específicas nos cabeçalhos ao fazer pedidos.
A resposta contém o código de status e a frase que você pode estar familiarizado com 404 erros, 500 erros de servidor ou redirecionamentos 301 e 302. O W3.org tem todos os códigos de erro HTTP definidos e descritos, um bom recurso, se você precisar descobrir o que significa um erro.
O corpo contém a resposta e geralmente é onde você precisará procurar as coisas boas. Nesse caso, recebemos HTML – o HTML completo da página inicial do Google. Ao trabalhar com APIs REST, é uma prática padrão receber uma sequência de dados codificada por JSON. Ocasionalmente, as APIs solicitarão que você adicione uma string específica ao corpo ao fazer solicitações também.
A seção de cookies conterá todos os cookies recebidos com a mensagem.
Como você pode ver, enviar um pedido com a API HTTP é muito simples. O que torna o trabalho com HTTP um pouco difícil é que as APIs REST podem ser muito sensíveis aos dados inseridos corretamente (o que é uma coisa boa), então, se você ignorar uma linha ao ler documentos da API, você pode acabar com algo que não funciona.
Trabalhando com APIs
Eu acho que é uma aposta segura que a maioria de vocês usará o HTTP para interagir com as APIs REST na web, caso em que você precisará usar o segundo parâmetro para especificar o número de coisas, autenticar-se e evitar algumas armadilhas comuns. Vamos começar com um exemplo simples – recuperar pinos de uma placa Pinterest.
Todas as APIs adequadas requerem autenticação, mas vamos enganar um pouco aqui usando o gerador de token Pinterest . Depois de autorizá-lo, você receberá um token de acesso que você pode usar. Vamos fazer um pedido e listar alguns pinos!
| $ Request = wp_remote_get (‘https://api.pinterest.com/v1/boards/marticz/home-office/pins/?access_token= < seu token de acesso >’); | |
| $ Pins = json_decode ($ request [‘body’], true); | |
| Se (! Empty ($ pins [‘data’])) { | |
| Echo ‘< ul >’; | |
| Foreach ($ pins [‘data’] como $ pin) { | |
| echo ‘< li > < a href = “ ‘$ pino. [‘ url ‘].’ “ >’. $ Pin [‘nota’]. ‘</ A > </ li >’; | |
| } | |
| Echo ‘</ ul >’; | |
| } |
Coloquei o código acima no content-page.phparquivo em Twenty Fifteen para testar como ele funciona. O resultado é uma página que exibe os pinos recentes de uma placa Pinterest sobre os Escritórios de Casa .
Certifique-se de usar seu próprio token na primeira linha. A linha dois decodifica o corpo da resposta para que possamos usar a matriz. Os pinos são armazenados, $pins['data']então eu apenas passei os itens e os mostrei em uma lista simples.
Autenticação
A autenticação geralmente é onde muitas pessoas viajam porque requer pelo menos mais um passo e, geralmente, alguns cabeçalhos também.
Vejamos a API do Twitter como um exemplo, mais especificamente as autenticações de aplicativos, que você pode usar para autenticar seu aplicativo com o Twitter.
Leia a documentação
O primeiro lugar onde você pode bagunçar não está lendo a documentação completamente. Se você é um veterano experiente da API REST, você pode pular direto para a seção Autenticação e simplesmente passar por ela.
Se você fizer isso, você pode ignorar uma linha escondida em uma lista que diz:
O corpo do pedido deve ser grant_type = client_credentials.
Omitir isso resultará em falha completa, mesmo que tudo o mais esteja perfeitamente implementado. Para parar de adivinhar o seu código, certifique-se de ler tudo completamente.
Adicionar cabeçalhos e outros parâmetros
Depois de seguir as instruções na documentação à carta, construí um pedido POST, o que deve gerar um token de acesso para mim. Veja como parece.
| $ Key = base64_encode (urlencode (“n8KP16uvGZA6xvFTtb8IAA: i4pmOV0duXJv7TyF5IvyFdh5wDIqfJOovKjs92ei878”)); | |
| $ Request = wp_remote_post (‘https://api.twitter.com/oauth2/token’, array ( | |
| ‘Headers’ => array ( | |
| ‘Autorização’ => ‘Básico’. $ Chave, | |
| ‘Content-Type’ => ‘application / x-www-form-urlencoded; charset = UTF-8’ | |
| ), | |
| ‘Body’ => ‘grant_type = client_credentials’, | |
| ‘Httpversion’ => ‘1.1’ | |
| )); | |
| $ Token = json_decode ($ request [‘body’]); | |
| Eco “< pre >”; Var_dump ($ token); Eco “</ pre >”; |
O primeiro passo é a URL codificar o token de acesso e o segredo (nem os tokens de acesso reais, desculpe). Eu adicionei dois cabeçalhos, um é um cabeçalho de autorização, que contém as credenciais de acesso. O segundo é um cabeçalho de tipo de conteúdo, que o Twitter me pediu para adicionar.
O corpo também foi preenchido como eu indiquei acima e a versão HTTP também foi adicionada, o Twitter também solicita isso. A resposta, entre outras coisas, conterá o seu token de acesso final na seção do corpo. Você precisará desse token em todas as outras chamadas subseqüentes para a API.
Armazenando em cache o token de acesso
O token é válido há algum tempo, solicitando-o em cada carregamento de página ou qualquer momento em que seu aplicativo precisa fazer algo é um desperdício e você terá taxa limitada. No WordPress, você pode usar um transiente para armazenar o valor e usar o transiente em cada chamada subseqüente.
| $ Token = get_transient (‘twitter_access_token’); | |
| $ Token = (vazio ($ token))? Get_twitter_access_token (): $ token; | |
| $ Request = wp_remote_get (‘https://api.twitter.com/1.1/followers/ids.json?screen_name=danielpataki & count = 5′, array ( | |
| ‘Headers’ => array ( | |
| ‘Autorização’ => ‘Portador’. $ Token, | |
| ‘Content-Type’ => ‘application / x-www-form-urlencoded; charset = UTF-8’ | |
| ), | |
| ‘Httpversion’ => ‘1.1’ | |
| )); | |
| $ Token = json_decode ($ request [‘body’]); |
Este pedido para a API do Twitter deve resultar em cinco dos meus seguidores listados (lista simples de IDs). Eu recupero meu token de um transiente, e se ele não existir eu uso a get_twitter_access-token()função para pegar um. Esta função também deve adicionar o token de acesso ao transiente, então a próxima vez será recuperado a partir daí.
Note que esta não é uma ótima maneira de fazer as coisas, mas mostra a lógica bem. Eu, um cenário simples, eu simplesmente usaria a get_twitter_access_token()função, que cuidaria todos os ifs.
Funções auxiliares da API HTTP
Agora que temos uma boa compreensão sobre o que é tudo para isso, vejamos todas as funções que a API HTTP do WordPress ajuda. Existem quatro funções para fazer pedidos com:
- Wp_remote_get ()
- Wp_remote_post ()
- Wp_remote_head ()
- Wp_remote_request ()
Estes são bastante auto-explicativos, o último wp_remote_request(), é uma função generalizada que você pode usar com qualquer verbo HTTP.
Cinco outras funções permitem recuperar as respostas com facilidade usando funções padronizadas em vez de se preocupar com as chaves da matriz.
- Wp_remote_retrieve_body ()
- Wp_remote_retrieve_header ()
- Wp_remote_retrieve_headers ()
- Wp_remote_retrieve_response_code ()
- Wp_remote_retrieve_response_message ()
Muito fácil de entender mais uma vez. Quando possível, use essas funções em vez de entrar nas matrizes de resposta manualmente. Isso ajudará outros desenvolvedores a seguir e usar ganchos se eles estiverem disponíveis no futuro.
Trabalhando com APIs
Como você pode ver, a interação com as APIs REST é extremamente fácil usando a API HTTP do WordPress e algumas outras funções do WordPress, como transientes. Eu recomendo fazer tudo isso uma tentativa, porque o desenvolvimento do WordPress está em direção confiável para um mundo impulsionado pela API – salte agora antes que seja tarde demais!
Se você quiser mais informações sobre o HTTP em geral, eu posso recomendar o Guia de James Marshall , que fala extensivamente sobre verbos HTTP, recursos, erros e outras coisas assim.
Se você tiver dúvidas sobre como usar a API HTTP ou ter idéias sobre como você poderia usá-la, avise-nos nos comentários abaixo.
