Utilizando a API do Twitter no desenvolvimento de aplicações web com PHP e cURL

Veja neste artigo como utilizar a API do Twitter no desenvolvimento de aplicações web PHP e cURL.

por Otávio Calaça Xavier

Apesar de já existir desde meados de 2001, a geração atual da Web só foi conceituada por Tim O'Reilly em 2005. Atualmente, a Web 2.0 representa a maior parcela dos sites e aplicativos Web. Também chamada de Web Social, nesta geração o foco é o compartilhamento e o colaborativismo. Isso fica claro em redes sociais online, grandes cases da Web 2.0. Um exemplo bastante conhecido deste conceito de redes sociais é o jogo Colheita Feliz, presente no Orkut, e o Farmville do Facebook.

Ultimamente, uma rede social que vem ganhando destaque especial é o Twitter. Criado em 2006 por Jack Dorsey, Evan Williams e Biz Stone, o Twitter já é a terceira rede social mais popular do mundo, ficando atrás apenas do Facebook e MySpace. Sua popularização rápida se deu, em grande parte, pela simplicidade de uso. Outro aspecto que colaborou para seu crescimento exponencial é sua API.

No Twitter, cada usuário possui um histórico de pequenas mensagens sobre coisas que estão acontecendo ou que ele está sentindo. Cada mensagem é chamada de tweet e deve possuir no máximo 140 caracteres. As conexões entre os usuários são realizadas com o conceito de seguir (são unilaterais).

A API do Twitter permite que diversos aplicativos conectem-se a ele para os mais variados fins. A partir de sua API, o Twitter começou a ser utilizado em aplicações rodando em dispositivos móveis, periféricos, entre outros. O funcionamento desta API é baseado em algumas tecnologias e conceitos como OAuth e REST. Neste contexto, este artigo irá apresentar tais conceitos e mostrar como utilizar alguns, em PHP, disponibilizados pela API do Twitter.

Conhecendo a API e o protocolo Oauth

A API do Twitter é composta por um conjunto de Web Services baseados na arquitetura REST Nesta arquitetura as mensagens trocadas são encapsuladas no protocolo HTTP e não no SOAP, como nos Web Services convencionais. O principal diferencial desta arquitetura é o foco em recursos e não nas chamadas a serviços.

A API do Twitter pode ser dividida em três partes:

• REST API: Esta é a principal API. É a que possui mais serviços e destina-se à manipulação dos dados dos usuários e conexões entre eles, bem como ao envio de mensagens. É importante observar que todas as APIs utilizam REST, mesmo que apenas esta tenha REST no nome.
• Search API: A API de busca disponibiliza serviços para pesquisa de mensagens e usuários.
• Streaming API: Esta API possui uma arquitetura um pouco diferenciada das duas primeiras. Destina-se a gerar conexões persistentes para troca de informações de forma síncrona. Isso é útil em sistemas desktop, ou que necessitem atualizar o histórico de mensagens constantemente.

Muitos serviços presentes na API necessitam de autenticação e autorização por parte do usuário. Em ambas as etapas, é utilizado o protocolo OAuth. O OAuth é um padrão aberto que permite aos usuários de um site garantirem acesso, por uma aplicação externa, aos seus recursos privados sem a necessidade de compartilhar suas senhas e logins. Para isso, o protocolo OAuth estipula um fluxo de comunicação entre a aplicação solicitante e a aplicação servidora (no caso o Twitter), como podemos observar na Figura 1. Esta figura mostra um diagrama contendo o fluxo de comunicação entre a aplicação consumidora e o Twitter. Os números em azul representam as etapas seguidas no processo de autenticação e descritas na sequência. É possível observar que o fluxo consiste em três etapas básicas: obtenção do token de requisição; autenticação e autorização pelo usuário e obtenção do token de acesso. Os tokens são únicos para cada sessão e expiram se não forem usados por alguns minutos seguidos.

Figura 1: Fluxo OAuth para obtenção do token de acesso à API do Twitter

Conforme podemos observar na Figura 1, inicialmente é necessário registrar a aplicação. Isso por que antes de começar o fluxo de comunicação, é necessário gerar uma API Key, uma Consumer Key e um Consumer Secret. Esse procedimento pode ser feito através do link http://dev.twitter.com/apps. Registrar uma aplicação permitirá ao twitter identificar sua aplicação.

Efetuado o registro da aplicação, passamos para a etapa 2: requisitar o token de requisição. Esse token é necessário para a autenticação e servirá para ser trocado pelo token de acesso mais à frente no processo. Para obter o token de requisição, é necessário acessar o link https://api.twitter.com/oauth/request_token passando os seguintes parâmetros (ver Listagem 1):

• oauth_nonce: uma chave aleatória usada para prevenir ataques (no exemplo: QP70eNmVz8jvdPevU3oJD2AfF7R7odC2XJcn4XlZJqk). Esta chave é aleatória e gerada automaticamente no processo de requisição do token.
• oauth_callback: uma URL para redirecionamento após a obtenção do token de requisição. No exemplo da Listagem 1 foi utilizada a URL http://localhost/process_callback.
• oauth_consumer_key: a chave de consumidor, adquirida no cadastro da aplicação (no exemplo: GDdmIQH6jhtmLUypg82g).
• oauth_version: a versão do OAuth a ser usado, a versão 2.0 ainda não é suportada (no exemplo será usada a 1.0).
• oauth_signature_method: o método de criptografia para a assinatura. Atualmente o Twitter suporta apenas HMAC-SHA1.
• oauth_timestamp: o timestamp atual, em formato Unix (no exemplo: 1272323042).
• oauth_signature: uma assinatura gerada a partir da concatenação do método de requisição com a URL requisitada e os parâmetros passados, em ordem alfabética.

Os parâmetros devem ser colocados no padrão URL-enconde, como no exemplo da Listagem 1.

Listagem 1: Token de requisição

POST&
https\%3A\%2F\%2Fapi.twitter.com\%2Foauth\%2Frequest_token&
oauth_callback\%3Dhttp\%253A\%252F\%252Flocalhost\%252F
process_callback\%26
oauth_consumer_key\%3DGDdmIQH6jhtmLUypg82g\%26
oauth_nonce\%3DQP70eNmVz8jvdPevU3oJD2AfF7R7odC2XJcn4XlZJqk\%26
oauth_signature_method\%3DHMAC-SHA1\%26
oauth_timestamp\%3D1272323042\%26
oauth_version\%3D1.0

A assinatura gerada consiste no Hash formado pela concatenação da Listagem 1 a partir do algoritmo informado no parâmetro oauth_signature_method. O algoritmo usado pelo Twitter necessita de chave. Com isso, a Consumer Secret (obtida no registro da aplicação) da aplicação é utilizada nesse momento para geração da assinatura. Os parâmetros são passados pelo cabeçalho Authorization do protocolo HTTP, como no exemplo da Listagem 2.

Listagem 2: Cabeçalho Authorization

OAuth
oauth_nonce="QP70eNmVz8jvdPevU3oJD2AfF7R7odC2XJcn4XlZJqk",
oauth_callback="http\%3A\%2F\%2Flocalhost\%2Fprocess_callback",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1272323042",
oauth_consumer_key="GDdmIQH6jhtmLUypg82g",
oauth_signature="8wUi7m5HFQy76nowoCThusfgB\%2BQ\%3D",
oauth_version="1.0"

O retorno dessa requisição é uma string com três parâmetros concatenados:

• auth_token, o token de requisição;
• oauth_token_secret, uma chave secreta que será usada no passo Obter Token de Acesso, e;
• oauth_callback_confirmed, que informa se a URL de retorno foi entendida corretamente.

Feito isso, chegou o momento de obter a autorização da aplicação pelo usuário. Para isso, o token obtido no passo anterior deverá ser enviado para a URL de autenticação/autorização. A URL pode ser https://api.twitter.com/oauth/authorize ou https://api.twitter.com/oauth/authenticate. A diferença está no fato de que com o método oauth/authorize o usuário terá que confirmar a autorização em todas as requisições, enquanto que com o método oauth/authenticate, o usuário só precisa autorizar a aplicação uma vez.

Caso não haja usuário logado, será exibido um formulário para login de usuário. Após sua autenticação, o usuário é requisitado a autorizar a aplicação. Uma vez autorizado o acesso, o fluxo é redirecionado para a URL de retorno informada no passo requisitar o token de requisição. Nesse redirecionamento são enviados dois parâmetros: oauth_token e oauth_verifier, que serão usados no próximo passo.

Com a autorização feita pelo usuário, o último passo é obter o token de acesso que será usado em todas as requisições futuras. Para isso, é feita uma requisição semelhante ao do passo requisitar o token de requisição para a URL https://api.twitter.com/oauth/access_token, com os parâmetros oauth_consumer_key, oauth_signature_method, oauth_version, oauth_nonce, oauth_timestamp já descritos e alguns novos parâmetros:

• oauth_token: o token de requisição, reenviado para a URL de retorno no passo anterior.
• oauth_verifier: um código verificador, gerado pela autorização do usuário. Esse código é enviado à URL de retorno, no passo anterior.

Novamente deve ser enviado um parâmetro oauth_signature que será o hash da concatenação dos parâmetros conforme pode ser observado na Listagem 3.

Listagem 3: Token de acesso.

POST&
https\%3A\%2F\%2Fapi.twitter.com\%2Foauth%2Faccess_token&
oauth_consumer_key\%3DGDdmIQH6jhtmLUypg82g\%26
oauth_nonce\%3D9zWH6qe0qG7Lc1telCn7FhUbLyVdjEaL3MO5uHxn8\%26
oauth_signature_method\%3DHMAC-SHA1\%26
oauth_timestamp\%3D1272323047\%26
oauth_token\%3D8ldIZyxQeVrFZXFOZH5tAwj6vzJYuLQpl0WUEYtWc\%26
oauth_verifier\%3DpDNg57prOHapMbhv25RNf75lVRd6JDsni1AJJIDYoTY\%26
oauth_version\%3D1.0

Para gerar o Hash é utilizado o mesmo método do passo requisitar o token de requisição. Entretanto, agora a chave para a criptografia será a concatenação entre o Consumer Secret e o oauth_token_secret, obtido no passo requisitar o token de requisição. O retorno da requisição é composto pelo token de acesso, uma palavra chave secreta, o ID e o nome do usuário que autorizou a aplicação. O token de acesso, retornado no passo obter o token de acesso será utilizado em todas as requisições de recursos e serviços para a API.

Implementação com PHP e cURL

Pode-se observar que as requisições realizadas no Twitter, para autenticação e autorização, não são comuns. Isso se dá pelo uso da versão 1.0 do protocolo OAuth. Para fazer requisições como essas, é necessário um cliente em que seja possível a edição do cabeçalho HTTP.

O cURL é uma biblioteca interessante para essa funcionalidade. As Listagens 4 e 5 mostram códigos que utilizam essa biblioteca em conjunto com a linguagem de programação PHP, como exemplo.

Na Listagem 4 é apresentado um script em PHP que realiza os passos do protocolo OAuth, exibidos na Figura 1, para autenticação e autorização de uma aplicação na API do Twitter. O script em questão pode ser considerado a aplicação consumidora do serviço. Neste script, inicialmente incluímos a função sendOAuthReg e iniciamos uma sessão para armazenar o token_secret (linhas 2 e 3). Na sequência, definimos o valor dos parâmetros consumer_key e consumer_secret obtidos durante o registro da aplicação no twitter (linhas 4 e 5). Depois disso, tentamos obter o token de acesso (linha 7), enviamos o token de requisição e verificação (linhas 8 e 9) e fazemos a requisição pelo token de acesso (linhas 10 e 11). De posse do token de acesso, damos início à obtenção do token de requisição nas linhas 16 e 17. Depois de obter o token de requisição, armazenamos ele (linha 20) e, por último, criamos o link para autorização com o token de requisição obtido (linhas 20 a 23).

Listagem 4: Script PHP para obtenção de tokens usando a função sendOAuthReq

<?php
// Incluindo função sendOAuthReq
include 'sendOAuthReq.php';
// Será usada a sessão para armazenar o token_secret
session_start();
// Valores dados pela API do Twitter apos registro em
// http://twitter.com/oauth
define('CONSUMER_KEY', 
       "[… COLOQUE AQUI SUA CONSUMER_KEY …]");
define('CONSUMER_SECRET', 
       "[… COLOQUE AQUI SEU CONSUMER_SECRET …]");
// Se tiver sido enviado o parâmetro oauth_token
// tentar obter o token de acesso
if($_GET['oauth_token']) {
    // URL para requisição do token de acesso
    $url = "https://twitter.com/oauth/access_token";  
  // Token de requisição e verificador serão enviados
	    $param['oauth_token'] = $_GET['oauth_token'];
	    $param['oauth_verifier'] = $_GET['oauth_verifier'];
    // Faz requisição pelo token de acesso e trata resposta
	    $resposta =  sendOAuthReq($url, $param);
	  parse_str($resposta, $api);
    // Token de acesso;  
	  echo $api['oauth_token'];    
    // Destroi a sessão e encerra o script      
	  session_destroy();  
	  die;
	}
// URL para obtenção do token de requisição
	$url = "https://twitter.com/oauth/request_token";
// Faz requisição passando a URL de retorno desejada
	$param['oauth_callback'] = "http://localhost/process_callback";
	$resposta = sendOAuthReq($url, $param);
	parse_str($resposta, $api);
// Armazena o token secret na sessão
	$_SESSION['secret'] = $api['oauth_token_secret'];
// Cria link para autorização, com o token de requisição
	?>
	<a href="https://twitter.com/oauth/authenticate?
         oauth_token=<?php echo $api['oauth_token']?>">
    Autorizar no Twitter
	</a>

Já a Listagem 5 exibe a função sendOAuthReq, em PHP, utilizada para realizar as requisições OAuth para o servidor (Twitter). Neste código é possível ver um exemplo de requisição OAuth. Também é exemplificada a geração da assinatura em Hash a partir do método de criptografia HMAC-SHA1. Inicialmente temos os parâmetros comuns nas requisições (linhas 3 a 8). Depois disso, montamos a chave e a codificamos com o algoritmo HMAC_SHA1 (linhas 9 a 19). O próximo passo será montar o cabeçalho de autorização com os parâmetros (linha 20) e, por fim, requisitar a URL enviando os parâmetros com o cURL (linhas 22 a 34).

Listagem 5: Função PHP para envio de requisições OAuth utilizando cURL

<?php
function sendOAuthReq($url, $param, $post = false) {
    //Parâmetros comuns nas requisições
    $param['oauth_consumer_key'] = CONSUMER_KEY;
    $param['oauth_version'] = "1.0";
    $param['oauth_timestamp'] = time();
    $param['oauth_signature_method'] = "HMAC-SHA1";
    $param['oauth_nonce'] = md5(uniqid(rand(), true));
 // Ordenar parâmetros
    ksort($param);
    // Monta a chave e codifica com HMAC_SHA1
    $sign = 'POST&'.
	        rawurlencode($url)."&".  
	        rawurlencode(http_build_query($param).
            // Caso tenha parâmetros a ser enviados
            // por POST, concatena-os.
	        (($post) ? "&".http_build_query($post) : ""));
	  $sign = base64_encode(
	            hash_hmac('sha1', $sign,  
	            CONSUMER_SECRET."&".$_SESSION['secret'],  
	            true
	          )
	  );
	  $param['oauth_signature'] = $sign;
    // Monta cabeçalho Authorization com os parâmetros
	    $authHeader = "Authorization: OAuth ".
	                  http_build_query($param, null, ",");
    // Requisita a URL, enviando os parâmetros com cURL
	  $curlHandle = curl_init();  
	  curl_setopt($curlHandle, CURLOPT_URL, $url);  
	  curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($curlHandle, CURLOPT_HTTPHEADER, array($authHeader));  
	  curl_setopt($curlHandle, CURLOPT_POST, true);  
	  if($post) {  
	      curl_setopt($curlHandle, CURLOPT_POSTFIELDS, http_build_query($post));  
	  }  
	  $apiResponse = curl_exec($curlHandle);  
	  curl_close($curlHandle);  
	  return $apiResponse;
	}
	?> 

Feito isto, podemos utilizar a API no desenvolvimento de nossas aplicações. Nesse sentido, conheceremos alguns métodos da API a seguir.

Explorando alguns métodos da API

A API de busca (Search API) não necessita de autenticação pelo usuário. Ela pode ser usada mesmo que não haja alguma aplicação registrada e vinculada às requisições. Essa API possui apenas o método search. Ela está separada do restante da API por ter sido desenvolvida inicialmente fora do Twitter por uma empresa chamada Summize. Entretanto, em 2008 o Twitter comprou tal empresa. Existem planos para unificação dela com a REST API.

O método search faz buscas e retorna os resultados em quatro possíveis formatos: xml, json, rss e atom. Ele pode ser requisitado a partir da URL: http://search.twitter.com/search.format, sendo que format pode assumir um dos quatro formatos disponíveis. A expressão para busca é enviada através do parâmetro q. O mecanismo de busca da Search API é otimizado e mistura resultados populares com resultados recentes. Entretanto, isso pode ser alterado a partir do parâmetro result_type. Ele pode ser definido como mixed (padrão), popular ou recent. Também há o parâmetro geocode para busca de twitter a partir da localização geográfica do usuário, entre outros. O exemplo abaixo faz busca por Tweets populares contendo a palavra “Brasil”, retornando-os em formato JSON: https://search.twitter.com/search.json?q=Brasil&result_type=popular

A API principal do Twitter é responsável pela manipulação e consulta dos dados. Qualquer método dessa API é precedido da URI http://api.twitter.com/version/, sendo que version é a versão da API (atualmente 1).

Nessa API, alguns métodos não requerem autorização/autenticação. Os métodos que trazem informações disponíveis no site do Twitter para qualquer visitante (não logado) não requerem autorização. Para esses métodos, é suficiente fazer uma requisição HTTP convencional para sua URL.

Um exemplo é o método statuses/user_timeline. Tal método retorna os últimos envios de um usuário em ordem cronológica. É possível especificar qual o usuário através dos parâmetros user_id, enviando o ID ou screen_name, enviando o login do usuário.

O método trends também não requer autorização. Ele retorna palavras que são tendências (muito faladas) no Twitter. Esse método possui os sub-recursos:

• trends/current, que retorna os termos mais falados atualmente;
• trends/daily, que mostra as expressões mais populares em um dia específico e;
• trends/weekly para uma semana específica.

Também há filtros por localidade, a partir do recurso trends/available, que pode receber latitude (lat) e longitude (long) como parâmetros.

Os métodos que requerem autenticação devem ser requisitados de maneira semelhante às requisições para obtenção do token de acesso. Os parâmetros comuns em qualquer requisição são oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_version e oauth_signature_method, já descritos. Também é necessário enviar o parâmetro oauth_token, com o token de acesso previamente obtido.

Esses parâmetros são enviados pelo cabeçalho Authorization. Os parâmetros específicos do método requisitado são enviados por POST. A assinatura é formada conforme descrito anteriormente. Entretanto, também são concatenados os parâmetros passados por POST. A chave para a criptografia é composta pelo Consumer Secret e o oauth_token_secret obtido com o token de acesso. A Listagem 6 exibe um exemplo de requisição ao método statuses/update (linha 18), usando a função sendOAuthReq (linha 23). Esse método insere um novo post na timeline do usuário autenticado (linha 22).

Listagem 6: Script PHP que chama o método statuses/update usando a função sendOAuthReq

<?php
 include 'sendOAuthReq.php';
 // Valores dados pela API do Twitter apos registro em
 // http://twitter.com/oauth
 define('CONSUMER_KEY', 
        "[… COLOQUE AQUI SUA CONSUMER_KEY …]");
 define('CONSUMER_SECRET', 
        "[… COLOQUE AQUI SEU CONSUMER_SECRET …]");

  // Definindo token de acesso e chave secreta
 define('ACCESS_TOKEN', $_GET['oauth_token']);
 define('ACCESS_TOKEN_SECRET', 
        $_GET['oauth_token_secret']);
 $_SESSION['secret'] = ACCESS_TOKEN_SECRET;
 
 // Método a ser requisitado
 $url = "http://api.twitter.com/1/statuses/update.json";
 $param['oauth_token'] = ACCESS_TOKEN;
 
 // Inclusão de novo post na timeline
 $post['status'] = utf8_encode("Novo post no Twitter.");
 $retorno = sendOAuthReq($url, $param, $post);
 
 // Recebe retorno em JSON e coloca-o 
 // em objeto JavaScript
 ?>
 <script>
     retorno = <?php echo $retorno; ?>;
 </script>

Por fim, a API de fluxo contínuo (Streaming API) possui métodos para busca e exibição dos posts de usuários. Todos os métodos dessa API requerem autorização, sendo que alguns requerem contato direto com os desenvolvedores da API para liberação. Os filtros são semelhantes aos presentes na API de busca. Entretanto, o fluxo é continuo. Isso significa que à medida que os usuários vão enviando posts, a API atualiza os dados da consulta, incluindo novos resultados, sem a necessidade de novas requisições. Como dito anteriormente, esse tipo de requisição é útil em sistemas desktop ou que necessitem de requisitar continuamente o histórico de mensagens. O único formato de retorno suportado nessa API é o JSON.

Conclusão

Neste artigo foi apresentada a API do Twitter, bem como conceitos relacionados, como OAuth e REST. O código em PHP apresentado é apenas um exemplo de implementação, que pode ser realizada de outras formas.

Tem sido cada vez mais comum a presença de APIs em redes sociais com foco no desenvolvimento de aplicações sociais. Tais APIs garantem um acesso ubíquo, ou seja, de qualquer lugar que o usuário esteja, em vários tipos de dispositivos. O uso das funcionalidades presentes em redes sociais, como o Twitter, em suas aplicações, auxilia o desenvolvedor a criar aplicações mais interativas e colaborativas.