php services

Lorna Jane Mitchell

Novatec

Web Services em PHPAPIs para a web moderna

Authorized Portuguese translation of the English edition of titled PHP Web Services, ISBN 9781449356569 2013 Lorna Jane Mitchell. This translation is published and sold by permission of O'Reilly Media, Inc., the owner of all rights to publish and sell the same.

Traduo em portugus autorizada da edio em ingls da obra PHP Web Services, ISBN 9781449356569 2013 Lorna Jane Mitchell. Esta traduo publicada e vendida com a permisso da O'Reilly Media, Inc., detentora de todos os direitos para publicao e venda desta obra.

Novatec Editora Ltda. [2013].

Todos os direitos reservados e protegidos pela Lei 9.610 de 19/02/1998. proibida a reproduo desta obra, mesmo parcial, por qualquer processo, sem prvia autorizao, por escrito, do autor e da Editora.

Editor: Rubens PratesTraduo: Lcia Ayako KinoshitaReviso tcnica: Aurelio JargasReviso gramatical: Marta Almeida de SEditorao eletrnica: Carolina Kuwabata

ISBN: 978-85-7522-369-7

Histrico de impresses:

Junho/2013 Primeira edio

Novatec Editora Ltda.Rua Lus Antnio dos Santos 11002460-000 So Paulo, SP BrasilTel.: +55 11 2959-6529Fax: +55 11 2950-8869E-mail: [email protected]: www.novatec.com.brTwitter: twitter.com/novateceditoraFacebook: facebook.com/novatecLinkedIn: linkedin.com/in/novatec

VC20130610

14

captulo 1HTTP

HTTP o acrnimo de HyperText Transfer Protocol (Protocolo de Trans-ferncia de Hipertexto), e a base sobre a qual a web est construda. Toda transao HTTP consiste em uma solicitao e uma resposta. O pro-tocolo HTTP por si s composto de vrias partes: a URL para a qual a solicitao foi direcionada, o verbo usado, outros cabealhos e cdigos de status e, claro, o corpo das respostas, que o que geralmente vemos quando navegamos pela web usando um navegador.

Ao navegar pela web, no plano ideal, experimentamos uma jornada tran-quila, passando pelos vrios locais que queremos visitar. No entanto isso representa um contraste marcante com o que est acontecendo por trs das cortinas, medida que fazemos essa jornada. Ao prosseguirmos, clicando em links ou fazendo o navegador criar solicitaes para ns, uma srie de pequenos passos ocorre nos bastidores. Cada passo composto de um par solicitao/resposta; o cliente (geralmente, seu navegador ou telefone, se voc estiver navegando na web) faz uma solicitao ao servidor, e o servidor processa a solicitao e envia a resposta de volta. A cada passo ao longo do caminho, o cliente faz uma solicitao e o servidor envia a resposta.

Como exemplo, insira o endereo http://oreilly.com/ em um navegador e voc ver uma pgina semelhante quela mostrada na figura 1.1; as informa-es desejadas podero ser encontradas na pgina, ou os hiperlinks nessa pgina nos direcionaro para o caminho em direo a elas.

A pgina de web chega no corpo da resposta HTTP, mas ela conta somen-te parte da histria. O restante est em outros locais no trfego HTTP. Considere os exemplos a seguir.

15Captulo 1 HTTP

Figura 1.1 Pgina inicial da OReilly.

Cabealho da solicitao:

GET / HTTP/1.1

User-Agent: Mozilla/5.0 (X11; Linux i686) AppleWebKit/537.8 (KHTML, like Gecko)

Chrome/23.0.1246.0 Safari/537.8

Host: oreilly.com

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Accept-Encoding: gzip,deflate,sdch

Accept-Language: en-GB,en-US;q=0.8,en;q=0.6

Cabealho da resposta:

HTTP/1.1 200 OK

Date: Thu, 15 Nov 2012 09:36:05 GMT

Server: Apache

Last-Modified: Thu, 15 Nov 2012 08:35:04 GMT

Accept-Ranges: bytes

Content-Length: 80554

Content-Type: text/html; charset=utf-8

Cache-Control: max-age=14400

Expires: Thu, 15 Nov 2012 13:36:05 GMT

Vary: Accept-Encoding

Web Services em PHP16

Como voc pode ver, h uma quantidade enorme de outras informaes teis sendo trocadas via HTTP, que geralmente no so vistas quando usamos um navegador. Compreender essa separao entre cliente e ser-vidor, e os passos executados pelos pares solicitao e resposta, funda-mental para entender o HTTP e trabalhar com web services. Aqui est um exemplo do que acontece quando consultamos o Google procura de kittens (gatinhos):

1. Fazemos uma solicitao para http://www.google.com/ e a resposta con-tm um cabealho Location e um cdigo de status igual a 301 que nos envia para uma pgina regional de pesquisas; para mim, essa pgina http://www.google.co.uk/ (no Brasil, http://www.google.com.br).

2. O navegador segue a instruo de redirecionamento (sem confir-mao do usurio; os navegadores redirecionam por padro), faz uma solicitao para http://www.google.co.uk/ e recebe a pgina com a caixa de pesquisas (Somente por diverso, veja o cdigo-fonte dessa pgina. H muita coisa acontecendo!). Ns preenchemos o campo e acionamos a pesquisa.

3. Fazemos uma solicitao para https://www.google.co.uk/search?q=kittens (com mais alguns parmetros) e obtemos uma resposta que mostra os resultados de nossa pesquisa.

Na histria mostrada aqui, todas as solicitaes foram feitas pelo navega-dor, em resposta a aes do usurio, embora algumas ocorram nos bas-tidores, tais como seguir os redirecionamentos ou solicitar componentes adicionais. Todos os componentes de uma pgina, como imagens, folhas de estilo e outros, so acessados por meio de solicitaes separadas, tra-tadas por um servidor. Qualquer contedo carregado assincronamente (pelo JavaScript, por exemplo) tambm gera mais solicitaes. Quando trabalhamos com APIs, ns nos aproximamos mais das solicitaes e as fazemos de modo mais deliberado, mas os mecanismos so os mesmos que usamos para criar pginas de web bem bsicas. Se voc j estiver criando sites, ento j deve conhecer tudo o que necessrio para criar web services!

17Captulo 1 HTTP

Clientes e servidoresAnteriormente, neste captulo, falamos sobre uma solicitao e uma res-posta entre um cliente e um servidor. Quando criamos sites usando PHP, a parte em PHP sempre corresponde ao servidor. Quando usamos APIs, construmos o servidor em PHP, mas podemos tambm consumir APIs a partir do PHP. aqui que a situao comea a ficar confusa. Podemos criar tanto um cliente quanto um servidor em PHP, e as solicitaes e as respostas podem ser tanto de entrada quanto de sada ou ambas!

Quando construmos um servidor, seguimos padres semelhantes maneira pela qual criamos pginas de web. Quando uma solicitao chega, usamos o PHP para descobrir o que foi solicitado e elaboramos a resposta correta. Por exemplo, se desenvolvssemos uma API para que os clientes pudessem obter atualizaes sobre seus pedidos de maneira programtica, estaramos construindo um servidor.

Usar o PHP para consumir APIs significa que estamos criando um cliente. Nosso aplicativo PHP faz solicitaes a servios externos via HTTP e, ento, usa as respostas para seus prprios propsitos. Um exemplo de um cliente poderia ser uma pgina que busca seus tutes mais recentes e os apresenta.

No incomum que um aplicativo seja ambos, um cliente e um servidor, conforme mostrado na figura 1.2. Um aplicativo que aceite uma solicitao e, em seguida, chame outros servios para obter as informaes de que necessita para gerar a resposta estar atuando tanto como cliente quanto como servidor.

Figura 1.2 Aplicativo da web atuando como um servidor para o usurio, mas tambm como cliente para acessar outras APIs.


Quando estiver trabalhando em aplicativos como esse, tome cuidado com a maneira pela qual voc d nome s variveis que envolvam a palavra request (solicitao) para evitar confuso!

Fazendo solicitaes HTTPH algumas maneiras diferentes de se comunicar via HTTP. Nesta seo, abordaremos trs delas: Curl, ferramentas em seu navegador e o prprio PHP. A ferramenta que voc escolher depender totalmente de sua ex-perincia e do que voc est tentando realizar. Tambm daremos uma olhada em ferramentas para inspecionar e depurar o HTTP no captulo 9.

Os exemplos aqui utilizam um site que est configurado para registrar as solicitaes feitas a ele (http://requestb.in), o que perfeito para explorar a forma como diferentes solicitaes de API so vistas por um servidor. Para us-lo, acesse o site e crie um novo request bin (continer de solicitaes). Voc ver a URL necessria para a qual dever fazer solicitaes e ser redirecionado para uma pgina que mostra o histrico das solicitaes feitas a esse continer.

Outra maneira excelente de tentar fazer diferentes tipos de solicitaes usar os endereos reservados (http://example.com, http://example.net e http://example.org), definidos pelo IANA (Internet Assigned Numbers Authority) em http://www.iana.org/domains/special.

CurlO Curl uma ferramenta de linha de comando disponvel em todas as plataformas. Ele nos permite fazer qualquer solicitao imaginvel de web em qualquer formato, repetir essas solicitaes e observar, com detalhes, quais informaes, exatamente, so trocadas entre cliente e servidor. Com efeito, a sada de exemplo no incio deste captulo foi gerada pelo Curl. uma ferramenta brilhante e rpida para inspecionar o que est aconte-cendo com uma solicitao web, particularmente quando lidamos com aquelas que esto fora do escopo usual de um navegador.

19Captulo 1 HTTP

Em sua forma mais bsica, uma solicitao Curl pode ser feita desta maneira (substitua as URLs pelas suas):

curl http://requestb.in/example

Podemos controlar todos os aspectos da solicitao a ser enviada; alguns dos recursos mais comumente usados sero apresentados aqui e usados ao longo de todo este livro para ilustrar e testar as vrias APIs mostradas.

Se voc j criou sites antes, ento saber a diferena entre solicitaes GET e POST usadas na criao de formulrios web. A mudana entre GET, POST e outros verbos HTTP usando Curl realizada por meio da opo -X, de modo que uma solicitao POST pode ser feita especificamente usando o comando a seguir:

curl -X POST http://requestb.in/example

Existem algumas opes teis que podem ser usadas para obter mais in-formaes do Curl, alm do corpo da resposta. Experimente usar a opo v, pois ela mostrar de tudo: cabealhos das solicitaes, cabealhos das respostas e todo o corpo da resposta! Porm ela divide a resposta, envian-do as informaes de cabealho para STDERR e o corpo para STDOUT.

Se a resposta for razoavelmente extensa, poder ser difcil encontrar uma determinada informao quando estiver usando Curl. Para ajudar nesse caso, possvel combinar o Curl com outras ferramentas, como o less ou o grep; contudo o Curl mostra uma barra de progresso na sada quando est em operao normal, o que pode causar confuso para essas outras ferramentas. Para inibir a barra de progresso, utilize a opo s (mas tome cuidado, pois ela tambm inibe a apresentao dos erros do Curl). Pode ser produtivo usar -s em combinao com v para criar uma sada que possa ser enviada a um paginador, como o less, para que ela possa ser examinada de modo detalhado, por meio de um comando como este:

curl -s -v http://requestb.in/example 2>&1 | less

O 2>&1 extra est presente para enviar a sada de STDERR para STDOUT, de modo que voc possa ver os cabealhos e o corpo; por padro, somente o STDOUT seria visvel ao less.

Trabalhar com a web em geral, e com APIs em particular, significa tra-balhar com dados. O Curl nos permite fazer isso de algumas maneiras


diferentes. O modo mais simples enviar os dados juntamente com uma solicitao em pares chave/valor exatamente como ocorre quando um formulrio submetido na web utilizando a opo d. A opo usada tantas vezes quantos forem os campos a serem includos:

curl -X POST http://requestb.in/example -d name="Lorna" -d email="[email protected]" -d message="gostei desse tal HTTP"

As APIs aceitam seus dados em diferentes formatos; s vezes, os dados no podem ser POSTados como um formulrio, mas devem ser criados em formato JSON ou XML, por exemplo. Em casos como esse, todo o corpo de uma solicitao pode ser organizado em um arquivo e passado para o Curl. Inspecione a solicitao anterior, e voc ver que seu corpo foi enviado como:

name=Lorna&[email protected]&message=gostei desse tal HTTP

Em vez de enviar os dados como pares chave/valor na linha de comando, eles podem ser colocados em um arquivo chamado data.txt (por exemplo). Esse arquivo pode, ento, ser fornecido sempre que a solicitao for feita. Essa tcnica especialmente til para evitar linhas de comando muito extensas ao trabalhar com uma grande quantidade de campos, e ao enviar dados que no so de formulrios, tais como JSON ou XML. Para usar o contedo de um arquivo como corpo de uma solicitao, fornecemos o nome do arquivo precedido por @ com uma nica opo d para o Curl:

curl -X POST http://requestb.in/example -d @data.txt

Trabalhar com os recursos estendidos do HTTP exige a capacidade de trabalhar com vrios cabealhos. O Curl permite enviar qualquer cabe-alho desejado ( por isso que, do ponto de vista de segurana, nunca podemos confiar no cabealho!), usando a opo H, seguida do cabealho completo a ser enviado. O comando para definir o cabealho Accept para solicitar uma resposta HTML :

curl -H "Accept: text/html" http://requestb.in/example

Antes de passar do Curl para outras ferramentas, vamos dar uma olhada em mais um recurso: como lidar com cookies. Os cookies sero discutidos com mais detalhes em um captulo posterior, mas, por enquanto, impor-tante saber que os cookies so armazenados pelo cliente e enviados com as solicitaes, e que novos cookies podem ser recebidos juntamente com

21Captulo 1 HTTP

cada resposta. Os navegadores enviam cookies com as solicitaes como comportamento padro, mas no Curl preciso fazer isso manualmente, pedindo ao Curl que armazene os cookies em uma resposta e depois os utilize na prxima solicitao. O arquivo que armazena os cookies chama--se "cookie jar (pote de biscoitos); est claro que at mesmo os geeks em HTTP possuem senso de humor.

Para receber e armazenar cookies de uma solicitao digite:

curl -c cookiejar.txt http://requestb.in/example

A essa altura, cookiejar.txt pode ser alterado da maneira que voc julgar adequada (novamente, nunca confie em informaes provenientes de fora do aplicativo!) e, em seguida, enviado ao servidor com a prxima solici-tao que voc fizer. Para isso, use a opo b e especifique o arquivo no qual os cookies podero ser encontrados:

curl -b cookiejar.txt http://requestb.in/example

Para capturar cookies e envi-los novamente junto a cada solicitao, use as opes -b e -c, fazendo referncia ao mesmo arquivo cookiejar. Dessa maneira, todos os cookies de entrada sero capturados e enviados para um arquivo e sero enviados de volta ao servidor em qualquer solicitao subsequente, comportando-se exatamente como em um navegador.

Ferramentas para navegadoresTodas as verses mais recentes dos navegadores modernos (Chrome, Fire-fox, Opera, Safari, Internet Explorer) possuem ferramentas embutidas ou plug-ins disponveis para ajudar a inspecionar o HTTP que estiver sendo transferido; para servios simples, talvez voc ache que as ferramentas de seu navegador sejam uma maneira acessvel de trabalhar com uma API. Essas ferramentas variam entre os navegadores e so constantemente atualizadas, mas aqui esto algumas ferramentas favoritas para que voc possa ter uma ideia.

No Firefox, essa funcionalidade proporcionada pelo Developer Toolbar (Barra de Ferramentas do Desenvolvedor) e por vrios plug-ins. Muitos desenvolvedores de web esto familiarizados com o FireBug (http://getfire-bug.com/), que possui algumas ferramentas teis, mas h outra ferramenta desenvolvida especificamente para mostrar todos os cabealhos de todas


as solicitaes feitas pelo seu navegador: o LiveHTTPHeaders (http://li-vehttpheaders.mozdev.org/). Ao us-lo, podemos observar todos os detalhes de cada solicitao, conforme pode ser visto na figura 1.3.

Figura 1.3 LiveHTTPHeaders mostrando detalhes do HTTP.

Todos os navegadores oferecem alguma maneira de inspecionar e alterar os cookies que estiverem sendo usados para solicitaes em um determi-nado site. No Chrome, por exemplo, essa funcionalidade oferecida por uma extenso que se chama Edit This Cookie (Editar este cookie) e por outras extenses similares. Ela mostra os cookies j criados e permite que voc os edite ou apague e tambm permite adicionar novos cookies. D uma olhada nas ferramentas de seu navegador favorito e veja os cookies enviados pelos sites que voc visita com mais frequncia.

s vezes, cabealhos adicionais devem ser includos em uma solicitao, como, por exemplo, quando enviamos cabealhos de autenticao ou cabealhos especficos para indicar ao servio que queremos fazer uma depurao extra. Com frequncia, o Curl ser a ferramenta correta para esse tipo de tarefa, mas tambm possvel adicionar os cabealhos em seu navegador. Diferentes navegadores possuem diferentes ferramentas; no Chrome, experimente usar uma extenso chamada ModHeader, vista na figura 1.4.

23Captulo 1 HTTP

Figura 1.4 O plug-in ModHeader no Chrome.

PHPNo de se surpreender que haja mais de uma maneira de lidar com so-licitaes HTTP usando PHP, e cada um dos frameworks tambm oferece suas prprias contribuies. Esta seo est focada no PHP bsico e analisa trs diferentes maneiras de trabalhar com APIs: usando a extenso Curl que j vem com o PHP, usando a extenso pecl_http e fazendo chamadas HTTP usando o tratamento de streams do PHP.

Anteriormente neste captulo, discutimos uma ferramenta de linha de comando chamada Curl (veja Curl na pgina 18). O PHP possui seus prprios wrappers (empacotadores) para o Curl, portanto podemos usar a mesma ferramenta de dentro do PHP. Uma solicitao GET simples tem o seguinte aspecto:


funcionamento do Curl e possui uma documentao excelente e bastante abrangente em http://php.net. Nesse exemplo, ela foi usada para configurar a opo CURLOPT_RETURNTRANSFER para true, o que faz o Curl retornar os resultados da solicitao HTTP, em vez de apresent-los. Na maioria dos casos, essa opo deve ser usada para capturar a resposta, em vez de deixar que o PHP a ecoe medida que ocorrer.

Podemos usar essa extenso para fazer todos os tipos de solicitaes HTTP, incluindo enviar cabealhos personalizados, enviar dados no corpo e usar diferentes verbos para fazer nossa solicitao. D uma olhada neste exemplo, que envia alguns campos de formulrio e um cabealho Content-Type com a solicitao POST:

25Captulo 1 HTTP


'header' => array('Accept: application/json',

'Content-Type: application/x-www-form-urlencoded'),

'content' => http_build_query($data)

)

));

$result = file_get_contents($url, false, $context);

As opes so definidas como parte do contexto que criamos para deter-minar como a solicitao dever funcionar. Em seguida, quando o PHP abrir o stream, ele usar as informaes fornecidas para determinar como lidar corretamente com o stream incluindo enviar os dados fornecidos e definir os cabealhos corretos.

Como voc pode observar, h algumas opes diferentes para lidar com o HTTP, tanto a partir do PHP quanto da linha de comando, e voc ver todas elas sendo usadas ao longo deste livro. Todas essas abordagens esto voltadas para o PHP padro, mas se voc estiver trabalhando com um framework, provavelmente ele ir oferecer algumas funcionalidades parecidas; todos os frameworks estaro encapsulando um desses mto-dos, portanto ser til ter um bom domnio do que est acontecendo por dentro desses encapsulamentos. Aps experimentar vrios exemplos, comum eleger um com o qual voc trabalhar mais do que com os demais; todos eles podem executar a mesma tarefa, de modo que aquele que voc eleger ser o resultado tanto de sua preferncia pessoal quanto das ferramentas que estiverem disponveis (ou que podem se tornar dis-ponveis) em sua plataforma.

php services

Documents