Desvendando Serviços Web RESTful – Parte 2

Versão 1.0

06.08.2014


Esta segunda parte, mais prática, mostra o RESTful em termos do protocolo HTTP. Os exemplos usarão como base o serviço do Foursquare.

Caso tenha chegado até aqui buscando um tutorial da API do Foursquare, esse artigo também servirá para tal. Será explicado detalhadamente, por meio de exemplos, os métodos da API de busca, autenticação e checkin.

Como visto na Parte 1, o RESTful é todo baseado em padrões abertos (XML, JSON, etc) e no protocolo HTTP. Ele é um modelo semelhante ao da Web sendo que ao invés de receber páginas HTML, o cliente consome informações oferecidas pelo serviço. Essas informações são representadas através do conceito de recursos.

O recurso é qualquer coisa que pode ser ofertado para o cliente. Eles são acessados usando uma URI juntamente com determinado comando. Os comandos são os métodos do próprio protocolo HTTP que possibilita diferentes ações como criar, apagar, atualizar ou recuperar determinado recurso. Dessa forma, um serviço oferta recursos através de comandos que são operados sobre URI’s.

Normalmente um serviço RESTful é descrito por meio de métodos. Cada método do serviço é composto por uma URI e o respectivo método do protocolo HTTP.

As URI’s são nada mais do que uma URL que se segue depois do domínio do serviço. Caso o método precise de informações extras, os parâmetros do HTTP são usados.

Por exemplo, determinado recurso que segue o padrão CRUD (criar, atualizar, deletar e ler) pode ser estruturado usando os seguintes métodos e URI’s:

Método do Serviço Método HTTP URI
Recuperar todos os livros GET /books
Recuperar livro GET /book/{id}
Atualizar livro POST /books/{id}
Atualizar livro PUT /books/{id}
Apagar livro DELETE /books/{id}

Lembrando que essa é uma das formas de organizar o acesso a um recurso, que segue um padrão para as URI’s e uma correlação semântica com os métodos do HTTP.

No serviço do Foursquare, um dos principais recursos ofertados é o venue.

Ele representa o conceito de lugares ao redor do mundo que podem ser visitados pelas pessoas. Utilizando a API podemos, por exemplo, adicionar novos lugares, curtir, buscar lugares próximos, como também fazer checkin em um lugar.

Para cada uma dessas funcionalidades são definidos métodos HTTP, URI’s e parâmetros. A figura abaixo resume os métodos para criar, buscar e fazer checkin em lugares. Os métodos para buscar e checkin serão explicados mais adiante.

Métodos do serviço do Foursquare

Alguns dos métodos do serviço do Foursquare

Para enchegarmos como o HTTP é usado em cada uma dessa requisições e respostas vou utilizar o plugin do Chrome REST Console por ele ser simples e de rápida utilização. Apesar de ser simples, ele possui todos os recursos para testar um serviço RESTFul como envio de dados em XML, JSON, manipulação do cabeçalho, autenticação, etc.

Outro software que gosto bastante é o SoapUI que pode ser utilizado para testar tanto serviços REST como outros tipos de serviços. Sua interface é bastante poderosa possibilitando salvar um projeto ao contrário do REST Console.

Neste artigo irei utilizar como base a API do Foursquare para exemplificar as requisições a um serviço RESTFul. Como todas as API’s existentes, uma camada de segurança é usada para controlar o acesso e prover autenticação. Os passos a seguir descrevem como obter acesso a API e em seguida os métodos de busca de lugares, checkin e adição de lugares serão apresentados.

Ao contrário de outras API’s, o acesso aos métodos pode ser feito utilizando autenticação OAuth2 ou um par de chaves associadas a uma aplicação registrada. Os métodos na API que criam recursos utilizam OAuth2, já aqueles para listar ou de busca precisam apenas dos pares de chaves. Todos os dois tipos serão explicados aqui.

O acesso começa criando uma aplicação. Para comecar crie uma conta no foursquare e depois va até o link e clique em “Create a new APP” para registrar uma nova aplicação. Digite o nome da sua aplicação e na parte “Web Addresses” informe para o campo “Welcome URL” a URL http://localhost:3000/welcome e para o campo “Redirect URI” digite o endereço http://localhost:3000/redirect_url. O campo redirect uri é importante, pois será a URL necessária para podermos receber o token de acesso quando usando autenticação OAuth2.

Ao criar a aplicação recebemos duas chaves o Client ID e o Client Secret. Através dessas duas chaves já podemos utilizar o método para buscar lugares. Ele possui como URI /venues/explore, o método GET e uma serie de parâmetros para direcionar a busca. Consulte a documentação para mais detalhes.

Buscaremos lugares cujos nomes contenham determinada palavra-chave (parâmetro query) e estão localizados dentro de determinada cidade (parâmetro near). Por exemplo, a URI final para buscar lugares que vendem açai fica:

https://api.foursquare.com/v2/venues/explore?
near=JoaoPessoa&query=Acai&client_id=SEU_CLIENT_ID&
client_secret=SEU_CLIENT_SECRET&v=20131016

A URL do serviço é https://api.foursquare.com/v2 e precede a URI do recurso. Observe que precisamos passar como parâmetros da requisição o client id (client_id), o client secret (client_secret) da aplicação que acabamos de criar e a versão da api (v).

Para executar o método no Chrome abra o plugin Rest Console. Em seguida vá até a seção Target e no campo Request URI coloque a URI anterior. No campo Content-Type digite application/json, no campo Request Method escolha GET e por fim clique no botão Send para enviar a requisição. Ao terminar a requisição a resposta é recebida e exibida na seção Response.

O campo content-type é um campo da requisição que indica qual o tipo de conteúdo a ser recebido. Por exemplo, no caso de receber XML passariamos application/xml no content-type.

Usando o Rest Console

Usando o Rest Console

O método explore retorna uma lista de lugares (venue) dentro do objeto json response. O código abaixo exibe o JSON da resposta simplificado com apenas dois dos vinte lugares retornados na resposta.

{
"meta": {
    "code": 200
},
"response": {
    ...
    "venue": {
        "id": "4c6b0783e503c928332947b3",
        "name": "Manaçaí",
        "contact": {
            "phone": "+558332469207",
            "formattedPhone": "+55 83 3246-9207",
            "twitter": "manacaioficial"
        },
        "location": {
            "address": "Av. Euzely Fabrício de Souza, 681",
            "crossStreet": "Av. Sapé",
            "lat": -7.103021972897571,
            "lng": -34.83786106109619,
            "postalCode": "58038-382",
            "cc": "BR",
            "city": "João Pessoa",
            "state": "PB",
            "country": "Brazil",
            "formattedAddress": ["Av. Euzely Fabrício de Souza, 681 (Av. Sapé)", "João Pessoa, PB", "58038-382", "Brazil"]
        },
        ...
        "hereNow": {
            "count": 1,
            "summary": "One person here",
            "groups": [{
                "type": "others",
                "name": "Other people here",
                "count": 1,
                "items": []
            }]
        }
    },
    "venue": {
        "id": "4f85ec60e4b048403d30bb67",
        "name": "Jampaçai",
        "contact": {
            "phone": "+558335784606",
            "formattedPhone": "+55 83 3578-4606"
        },
        "location": {
            "address": "R. Fernando Luiz Henrique dos Santos, 616, Lj. 9",
            "lat": -7.091750909473074,
            "lng": -34.83541126461676,
            "postalCode": "58038-000",
            "cc": "BR",
            "city": "João Pessoa",
            "state": "PB",
            "country": "Brazil",
            "formattedAddress": ["R. Fernando Luiz Henrique dos Santos, 616, Lj. 9", "João Pessoa, PB", "58038-000", "Brazil"]
        },
        ...
        "hereNow": {
            "count": 0,
            "summary": "0 people here",
            "groups": []
        }
    }
}

Continuando com o uso do serviço, o próximo método é o de fazer checkin em determinado lugar. No caso desse método precisaremos usar o esquema de autenticação OAuth2 do foursquare.

Ele consiste basicamente em passar como parâmetro de cada requisição um token de acesso. Para obter o token de acesso acesse a seguinte URL no seu navegador:

https://foursquare.com/oauth2/authenticate?
client_id=SEU_CLIENTE_ID&response_type=token&
redirect_uri=http://localhost:3000/redirect_url

O client_id é o cliente id da aplicação, o redirect_uri é a URL de redirecionamento para receber o token de acesso. Ele deve ser necessáriamente o mesmo valor especificado no campo “Redirect URI” quando criamos a aplicação. Caso seja diferente ocorrerá o seguinte erro “Cause of error: Callback uri is not valid for this consumer”.

Por último temos o response_type que é o parâmetro indicando que queremos obter o token de acesso. Ao acessar o link acima recebemos outro link no navegador que contém o token de acesso. Esse link será como:

http://localhost:3000/redirect_url#access_token=SEU_TOKEN_DE_ACESSO

Nesse caso, no sucesso da autenticação o browser está sendo redirecionado para a URL de redirecionamento que especificamos e passando nosso token através do parâmetro access_token. Agora com o valor do parâmetro access_token podemos usar qualquer método da API que requer autenticação.

O checkin num lugar é feito com a URI /checkins/add, usando o método POST do HTTP. Ele possui como parâmetro obrigatório o id do lugar para checkin.

Para fazer um checkin, usando o plugin Rest Console, no campo Request Method mude para método POST e no campo Request URI entre com a seguinte URI:

https://api.foursquare.com/v2/checkins/add?
oauth_token=SEU_TOKEN_DE_ACESSO&
venueId=4f85ec60e4b048403d30bb67&
shout=Entrei aqui sem ser pelo aplicativo do foursquare. Não é demais?&
broadcast=facebook&v=20131016

O parâmetro oauth_token é o token de acesso que conseguimos na autenticação. Como estamos usando o token não precisamos mais passar o client_id. O parâmetro venueId especifica o id local do checkin e pode ser conseguido pela busca de lugar através do campo id da entidade venue. O parâmetro shout especifica uma mensagem de checkin e o broadcast indica que queremos compartilhar no facebook.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s