O WordPress HTTP API consiste em um conjunto de funções que o ajudarão a fazer chamadas HTTP com muito mais facilidade. Não há mais necessidade de brincar com file_get_contents ou cURL, apenas uma única interface unificada. Isto é fantástico para interagir com APIs de terceiros, especialmente APIs com REST, como Twitter, Facebook, MailChimp, e outras.
O básico do HTTP
Todos nós já vimos o HTTP em ação antes. Na verdade, se esta é sua primeira vez na web e esta é a primeira coisa que você está lendo, você já viu o HTTP trabalhando sua magia. HTTP é um protocolo de rede usado para entregar todos os arquivos e dados (recursos) através da Interwebs.
Há basicamente duas partes na equação: a solicitação HTTP e a resposta HTTP, ou transação. Tanto a solicitação quanto a resposta são muito semelhantes em estrutura, ambas têm quatro partes:
- Uma linha inicial
- Zero ou mais linhas de cabeçalho
- Uma linha em branco
- Um conteúdo corporal opcional
A linha inicial
As solicitações utilizam a linha inicial para enviar três informações: o nome do método, o caminho e a versão HTTP. Por exemplo, ao visualizar a página principal do blog Kinsta, você verá isto na linha inicial da solicitação.
GET /blog/ HTTP/1.1As respostas fornecem também três informações, embora um pouco diferentes: A versão HTTP, o código de resposta e uma descrição da resposta. Ao fazer uma solicitação ao blog principal Kinsta, ele enviará uma resposta HTTP com a seguinte linha inicial:
HTTP/1.0 200 OKCabeçalhos
Os cabeçalhos contêm vários pedaços de informação sobre a solicitação ou a resposta. HTTP 1.1 define 46 tipos de cabeçalhos, mas apenas um é necessário (apenas para solicitações), o cabeçalho “Host”. Veja a captura de tela de minhas ferramentas de desenvolvimento Chrome que mostra alguns dos cabeçalhos enviados junto com uma solicitação para o blog principal do Kinsta:
Corpo
O corpo geralmente contém dados sobre o recurso solicitado. Se você enviar uma solicitação de GET para o blog principal do Kinsta você deve receber o HTML necessário para renderizar a página (o recurso) no conteúdo do corpo.
Mais informações
Isso é tudo que você precisa saber agora mesmo sobre HTTP. Vamos nos concentrar principalmente no nome do método (GET,POST,etc), cabeçalhos e o corpo. Se você gostaria de saber mais, recomendo a explicação de James Marshall sobre HTTP, é uma cartilha muito bem escrita para suas necessidades HTTP.
Sobre as APIs Restful
APIs Restful, ou a metodologia REST tem como objetivo fornecer uma maneira simples e padrão de interagir com uma aplicação (aqui você pode aprender mais sobre os conceitos básicos do WordPress REST API). Ela é freqüentemente usada em conjunto com HTTP para criar um sistema muito compreensível de interações. Ele é baseado em caminhos e verbos HTTP.
Os Verbos HTTP são os mesmos nomes dos métodos que vimos anteriormente, os mais comuns são: GET, POST, PUT, DELETE. Eu acho que PUT é o único ambíguo aqui, pense nisso como um comando de atualização. Ao usar estes verbos junto com os caminhos, podemos construir um sistema significativo:
GET /post/1/ seria usado para recuperar o posto com o ID de 1. DELETE /post/1/ seria usado para apagar o mesmo posto. Poderíamos também usar PUT /post/1/ para atualizá-lo, fornecendo informações relevantes no corpo do pedido e cabeçalhos.
Tenho certeza de que você pode ver que apenas anexando uma versão HTTP aos nossos códigos acima temos a linha inicial de uma transação HTTP, o que é apenas uma das razões pelas quais este sistema é tão poderoso.
Usando o WordPress HTTP API
Munidos de todo esse conhecimento, podemos facilmente compreender como funciona o WordPress HTTP API. Os quatro métodos usados para fazer solicitações e interceptar as respostas são:
wp_remote_get()wp_remote_post()wp_remote_head()wp_remote_request()
As duas primeiras funções são auto-explicativas, elas utilizam os métodos GET e POST respectivamente no pedido. A terceira função usa o método HEAD, algo sobre o qual ainda não falamos. Este método é usado para recuperar apenas os cabeçalhos de uma resposta. Isto pode economizar muito overhead se precisarmos apenas de alguns metadados sobre um recurso. A função final é genérica, você pode especificar qual método você gostaria de usar dentro dos parâmetros da função.
Há cinco funções adicionais que podemos utilizar para recuperar partes específicas da resposta. Basicamente, são cortes para navegar a massa de dados que recebemos:
wp_remote_retrieve_body()wp_remote_retrieve_header()wp_remote_retrieve_headers()wp_remote_retrieve_response_code()wp_remote_retrieve_response_message()
Nossa primeira solicitação HTTP
Vamos fazer um teste rápido, recuperando as informações do cabeçalho do blog Kinsta. Você pode fazer isso em qualquer lugar dentro de um plugin ou tema, mas obviamente você deve estar dentro de um ambiente de teste para ter certeza de que não irá emitir textos indesejados em um site ao vivo.
$response = wp_remote_head( 'https://kinsta.com/blog/' );
var_dump( $response )Como você pode ver pela resposta que obtemos abaixo, a seção do corpo está vazia (já que estamos usando o método HEAD) e todos os cabeçalhos são mostrados. Para pegar somente os cabeçalhos sem todos os outros membros da matriz, poderíamos usar a função wp_remote_retrieve_headers().
array (size=5)
'headers' =>
array (size=13)
'server' => string 'nginx' (length=5)
'date' => string 'Wed, 22 Jul 2015 14:22:07 GMT' (length=29)
'content-type' => string 'text/html; charset=UTF-8' (length=24)
'connection' => string 'close' (length=5)
'vary' => string 'Accept-Encoding' (length=15)
'x-pingback' => string 'https://kinsta.com/xmlrpc.php' (length=29)
'x-powered-by' => string 'HHVM/3.8.0' (length=10)
'link' => string '; rel="https://github.com/WP-API/WP-API"' (length=68)
'x-frame-options' => string 'DENY' (length=4)
'x-content-type-options' => string 'nosniff' (length=7)
'strict-transport-security' => string 'max-age=31536000' (length=16)
'x-kinsta-cache' => string 'HIT' (length=3)
'content-encoding' => string 'gzip' (length=4)
'body' => string '' (length=0)
'response' =>
array (size=2)
'code' => int 200
'message' => string 'OK' (length=2)
'cookies' =>
array (size=0)
empty
'filename' => nullFazendo sentido das APIs
A maior barreira que eu vejo para os desenvolvedores é a enorme quantidade de coisas novas que eles precisam colocar em prática para fazer uma chamada API funcionar. você precisa saber sobre HTTP, como fazer solicitações e também como autenticar corretamente, sem isso, cada chamada falhará. Vejamos um exemplo através da API do Twitter, uma vez que eles têm uma ótima documentação.
Estaremos analisando a Autenticação somente para aplicações (que é um fluxo mais fácil), eu estarei passando pelos mesmos passos que o Twitter sugere. Antes de começarmos, certifique-se de criar um aplicativo no Twitter.
Você deve ser capaz de adicionar o código abaixo em qualquer lugar em um tema ou plugin, mas, como antes, certifique-se de usar um local de teste!
Passo 1: Codificar a chave e o segredo do consumidor
Uma vez criado um aplicativo, você deve ter uma chave do consumidor e um segredo em mãos. Para facilitar as coisas, vamos criar constantes que guardem essas informações para nós.
define( 'TWITTER_CONSUMER_KEY', '12disnir382jeqwdasd23wdasi' );
define( 'TWITTER_CONSUMER_SECRET', '23wdajskduhtrq2c32cuq9r8uhuf' )As três etapas de criação de uma versão codificada destas estão dispostas nos documentos:
- URL codifica a chave do consumidor e o segredo do consumidor
- Concatê-las com um cólon
- Base64 codifica todo o cordão
Em PHP isso será muito fácil de fazer, aqui vai!
$key = urlencode( TWITTER_CONSUMER_KEY );
$secret = urlencode( TWITTER_CONSUMER_SECRET );
$concatenated = $key . ':' . $secret;
$encoded = base64_encode( $concatenated );
Passo 2: Obtendo um Token ao Portador
Em vez de usar sua senha real, você envia para o Twitter sua seqüência codificada (que usa suas credenciais API) e recebe um passe temporário que é válido por um determinado período de tempo. Para fazer isso, faremos um pedido HTTP, aqui está o que o Twitter tem a dizer:
- A solicitação deve ser uma solicitação HTTP POST.
- O pedido deve incluir um cabeçalho de Autorização com o valor de Basic .
- A solicitação deve incluir um cabeçalho Content-Type com o valor de aplicação/x-www-form-urlencoded;charset=UTF-8.
- O corpo do pedido deve ser grant_type=client_credentials.
Vamos começar com o básico. Sabemos que precisamos de um pedido de PÓS, então estaremos usando wp_remote_post(). A função leva aos parâmetros; o primeiro é o URL, o segundo contém argumentos opcionais. A URL será https://api.twitter.com/oauth2/token, usaremos o segundo parâmetro para lidar com todos os outros requisitos.
$args = array(
'headers' => array(
'Authorization' => 'Basic ' . $encoded,
'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8'
),
'body' => 'grant_type=client_credentials'
);
$response = wp_remote_post( 'https://api.twitter.com/oauth2/token', $args );
Os cabeçalhos precisam ser adicionados como uma matriz, sendo o tipo de cabeçalho a chave, o valor o valor do membro da matriz; O corpo deve ser uma corda. Se for bem sucedido, você deve ver uma resposta semelhante à que está abaixo.
array (size=5)
'headers' =>
array (size=23)
'cache-control' => string 'no-cache, no-store, must-revalidate, pre-check=0, post-check=0' (length=62)
'content-disposition' => string 'attachment; filename=json.json' (length=30)
'content-encoding' => string 'deflate' (length=7)
'content-length' => string '142' (length=3)
'content-type' => string 'application/json;charset=utf-8' (length=30)
'date' => string 'Wed, 22 Jul 2015 14:47:37 GMT' (length=29)
'expires' => string 'Tue, 31 Mar 1981 05:00:00 GMT' (length=29)
'last-modified' => string 'Wed, 22 Jul 2015 14:47:37 GMT' (length=29)
'ml' => string 'A' (length=1)
'pragma' => string 'no-cache' (length=8)
'server' => string 'tsa_b' (length=5)
'set-cookie' => string 'guest_id=v1%3A14375720938219946; Domain=.twitter.com; Path=/; Expires=Fri, 21-Jul-2017 14:47:37 UTC' (length=100)
'status' => string '200 OK' (length=6)
'strict-transport-security' => string 'max-age=631138519' (length=17)
'x-connection-hash' => string 'd8b10926f99dwef93rd7edbe5a71a97a' (length=32)
'x-content-type-options' => string 'nosniff' (length=7)
'x-frame-options' => string 'SAMEORIGIN' (length=10)
'x-response-time' => string '34' (length=2)
'x-transaction' => string 'ef0ebwefweece62ef' (length=16)
'x-tsa-request-body-time' => string '0' (length=1)
'x-twitter-response-tags' => string 'BouncerCompliant' (length=16)
'x-ua-compatible' => string 'IE=edge,chrome=1' (length=16)
'x-xss-protection' => string '1; mode=block' (length=13)
'body' => string '{"token_type":"bearer","access_token":"AAAAAAAAAAAAAAAAAAAAAFoafQAAAAAAqg%2BxmuH83hjsod6crH5bKTUX9Arc%3D5dWpp0XCTDjyiXxMC7LDLg8JbzPdGlCsJi2R1qjY1FMksTAFyG"}' (length=155)
'response' =>
array (size=2)
'code' => int 200
'message' => string 'OK' (length=2)
'cookies' =>
array (size=1)
0 =>
object(WP_Http_Cookie)[303]
public 'name' => string 'guest_id' (length=8)
public 'value' => string 'v1:143757645770219946' (length=21)
public 'expires' => int 1500648457
public 'path' => string '/' (length=1)
public 'domain' => string '.twitter.com' (length=12)
'filename' => nullO principal destaque de tudo isso é a ficha de acesso que pode ser encontrada no corpo da resposta. Vamos recuperar isso agora usando nossas úteis funções de WordPress. Continuando a partir de nosso exemplo anterior, poderíamos pegar o token de acesso usando o seguinte código:
$body = wp_remote_retrieve_body( $response );
$body = json_decode( $body, true );
$access_token = $body['access_token'];Etapa 3: Utilize o Token ao Portador
O último passo é simplesmente usar esta ficha portadora em todas as outras chamadas API. Precisamos adicioná-lo como um cabeçalho de “Autorização” com o valor: Bearer [bearer_token]. Vamos fazer uma simples chamada API que irá recuperar os últimos tweets de um usuário usando o caminho user_timeline.
$url = 'https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=danielpataki&count=3';
$args = array(
'headers' => array(
'Authorization' => 'Bearer ' . $access_token,
),
);
$response = wp_remote_get( $url, $args );
$tweets = json_decode( wp_remote_retrieve_body($response), true )
No final de tudo isso, a variável $tweets conterá uma variedade de tweets. Você pode usar várias propriedades desta matriz para exibir o tweet ou manipular os dados.
Conclusão
Como você pode ver, usar o WordPress HTTP API para se conectar a serviços externos não é tão difícil. Muitas das APIs modernas de hoje são construídas em torno dos mesmos princípios REST – uma vez que você aprende uma, você vai pegar o jeito de outras muito rapidamente.
Tenha em mente que sempre que a documentação lhe pedir para usar o corpo, use o corpo e quando ele pedir cabeçalhos, basta adicionar quantos forem necessários. Depois, olhe a resposta, converta-a em uma matriz, pegue os dados necessários e use-os, é tão simples quanto isso.
Se alguém já trabalhou com uma API particularmente boa ou ruim antes, ou se você tem algumas dicas e truques usando a API HTTP do WordPress, informe-nos nos comentários!
Oi, meu nome é Daniel, sou o CTO aqui na Kinsta. Você talvez me conheça da Smashing Magazine, WPMU Dev, Tuts+ e outras revistas de WordPress/Desenvolvimento. Além de WordPress e PHP, passo a maior parte do meu tempo com Node, React, GraphQL e outras tecnologias no espaço Javascript. Quando não estou trabalhando para criar a melhor solução de hospedagem do universo, coleciono jogos de tabuleiro, jogo pebolim no escritório, viajo ou toco guitarra e canto em uma banda não muito boa.
Deixe um comentário